idnits 2.17.1 draft-ietf-oncrpc-rpcsec_gss-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-18) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. ** Bad filename characters: the document name given in the document, 'draft-ietf-oncrpc-rpcsec_gss-01', contains other characters than digits, lowercase letters and dash. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 2 instances of too long lines in the document, the longest one being 3 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 186 has weird spacing: '...ue_auth cred;...' == Line 187 has weird spacing: '...ue_auth verf;...' == Line 773 has weird spacing: '... octet lengt...' == Line 904 has weird spacing: '...sed for encry...' == Couldn't figure out when the document was first submitted -- there may comments or warnings related to the use of a disclaimer for pre-RFC5378 work that could not be issued because of this. Please check the Legal Provisions document at https://trustee.ietf.org/license-info to determine if you need the pre-RFC5378 disclaimer. -- The document date (November 1996) is 10016 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '0' on line 206 -- Possible downref: Non-RFC (?) normative reference: ref. 'Eisler' -- Possible downref: Non-RFC (?) normative reference: ref. 'Jaspan' ** Obsolete normative reference: RFC 1508 (ref. 'Linn') (Obsoleted by RFC 2078) ** Obsolete normative reference: RFC 1831 (ref. 'Srinivasan-rpc') (Obsoleted by RFC 5531) ** Obsolete normative reference: RFC 1832 (ref. 'Srinivasan-xdr') (Obsoleted by RFC 4506) Summary: 13 errors (**), 0 flaws (~~), 6 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 ONC RPC Working Group M. Eisler 3 Internet Draft A. Chiu 4 Document: draft-ietf-oncrpc-rpcsec_gss-01.txt L. Ling 5 November 1996 7 RPCSEC_GSS Protocol Specification 9 Abstract 11 This memo describes an ONC/RPC security flavor that allows RPC 12 protocols to access the Generic Security Services Application 13 Programming Interface (referred to henceforth as GSS-API). 15 Status of this Memo 17 This document is an Internet-Draft. Internet-Drafts are working 18 documents of the Internet Engineering Task Force (IETF), its areas, 19 and its working groups. Note that other groups may also distribute 20 working documents as Internet-Drafts. 22 Internet-Drafts are draft documents valid for a maximum of six 23 months. This Internet-Draft expires in May, 1997. Internet-Drafts 24 may be updated, replaced, or obsoleted by other documents at any 25 time. It is not appropriate to use Internet-Drafts as reference 26 material or to cite them other than as "work in progress." 28 To learn the current status of any Internet-Draft, please check the 29 "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow 30 Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe), 31 munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or 32 ftp.isi.edu (US West Coast). 34 Comments on this document should be sent to the IETF ONCRPC Working 35 Group discussion list: 37 oncrpc-wg@sunroof.eng.sun.com 39 Distribution of this memo is unlimited. 41 Table of Contents 43 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2 44 2. Review of the RPC Message Protocol . . . . . . . . . . . . . . 3 45 3. Flavor Number Assignment . . . . . . . . . . . . . . . . . . . 6 46 4. New auth_stat Values . . . . . . . . . . . . . . . . . . . . . 6 47 5. Elements of the RPCSEC_GSS Security Protocol . . . . . . . . . 6 48 5.1. Version Negotiation . . . . . . . . . . . . . . . . . . . . 8 49 5.1.1. Version Inquiry Requests . . . . . . . . . . . . . . . . . 8 50 5.1.2. Version Inquiry Responses . . . . . . . . . . . . . . . . 8 51 5.1.2.1. Normal Version Inquiry Responses . . . . . . . . . . . . 8 52 5.1.2.2. Abnormal Version Inquiry Responses . . . . . . . . . . 10 53 5.1.2.3. Version Negotiation Examples . . . . . . . . . . . . . 10 54 5.2. Context Creation . . . . . . . . . . . . . . . . . . . . . 11 55 5.2.1. Context Creation Requests . . . . . . . . . . . . . . . 11 56 5.2.2. Context Creation Responses . . . . . . . . . . . . . . . 13 57 5.2.2.1. Context Creation Response - Successful Acceptance . . 13 58 5.2.2.1.1. Client Processing of Successful Context Creation 59 Responses . . . . . . . . . . . . . . . . . . . . . 14 60 5.2.2.2. Context Creation Response - Unsuccessful Cases . . . . 14 61 5.3. RPC Data Exchange . . . . . . . . . . . . . . . . . . . . 15 62 5.3.1. RPC Request Header . . . . . . . . . . . . . . . . . . . 15 63 5.3.2. RPC Request Data . . . . . . . . . . . . . . . . . . . . 16 64 5.3.2.1. RPC Request Data - No Data Integrity . . . . . . . . . 16 65 5.3.2.2. RPC Request Data - With Data Integrity . . . . . . . . 16 66 5.3.2.3. RPC Request Data - With Data Privacy . . . . . . . . . 17 67 5.3.3. Server Processing of RPC Data Requests . . . . . . . . . 17 68 5.3.3.1. Context Management . . . . . . . . . . . . . . . . . . 17 69 5.3.3.2. Server Reply - Request Accepted . . . . . . . . . . . 19 70 5.3.3.3. Server Reply - Request Denied . . . . . . . . . . . . 19 71 5.4. Context Destruction . . . . . . . . . . . . . . . . . . . 20 72 6. Security Considerations . . . . . . . . . . . . . . . . . . 21 73 6.1. Privacy of Call Header . . . . . . . . . . . . . . . . . . 21 74 6.2. Sequence number attacks . . . . . . . . . . . . . . . . . 21 75 6.3. Message stealing attacks . . . . . . . . . . . . . . . . . 22 76 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 22 77 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 22 78 9. Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 23 80 1. Introduction 82 This document describes the protocol used by the RPCSEC_GSS security 83 flavor. Security flavors have been called authentication flavors for 84 historical reasons. This memo recognizes that there are two other 85 security services besides authentication, integrity, and privacy, and 86 so defines a new RPCSEC_GSS security flavor. 88 The protocol is described using the XDR language [Srinivasan-xdr]. 89 The reader is assumed to be familiar with ONC RPC and the security 90 flavor mechanism [Srinivasan-rpc]. The reader is also assumed to be 91 familiar with the GSS-API framework [Linn]. The RPCSEC_GSS security 92 flavor uses GSS-API interfaces to provide security services that are 93 independent of the underlying security mechanism. 95 2. Review of the RPC Message Protocol 97 This memo refers to several fields of the RPC protocol. For 98 convenience of reviewers, as this document is in Internet-Draft 99 state, an XDR language description of the RPC message protocol is 100 provided here. 102 /* RPC message type */ 104 enum msg_type { 105 CALL = 0, 106 REPLY = 1 107 }; 109 /* Reply types */ 111 enum reply_stat { 112 MSG_ACCEPTED = 0, 113 MSG_DENIED = 1 114 }; 116 /* Security flavors */ 118 enum auth_flavor { 119 AUTH_NONE = 0, 120 AUTH_SYS = 1, 121 AUTH_SHORT = 2 122 }; 124 /* Status of accepted messages */ 126 enum accept_stat { 127 SUCCESS = 0, 128 PROG_UNAVAIL = 1, 129 PROG_MISMATCH = 2, 130 PROC_UNAVAIL = 3, 131 GARBAGE_ARGS = 4, 132 SYSTEM_ERR = 5 133 }; 135 /* Status of rejected messages */ 137 enum reject_stat { 138 RPC_MISMATCH = 0, 139 AUTH_ERROR = 1 140 }; 142 /* Why authentication failed */ 143 enum auth_stat { 144 AUTH_OK = 0, 146 /* failed at remote end */ 148 AUTH_BADCRED = 1, 149 AUTH_REJECTEDCRED = 2, 150 AUTH_BADVERF = 3, 151 AUTH_REJECTEDVERF = 4, 152 AUTH_TOOWEAK = 5, 154 /* failed locally */ 156 AUTH_INVALIDRESP = 6, 157 AUTH_FAILED = 7 158 }; 160 /* Opaque structure of credential and verifier */ 162 struct opaque_auth { 163 auth_flavor flavor; 164 opaque body<400>; 165 }; 167 /* The RPC message */ 169 struct rpc_msg { 170 unsigned int xid; 171 union switch (msg_type mtype) { 172 case CALL: 173 call_body cbody; 174 case REPLY: 175 reply_body rbody; 176 } body; 177 }; 179 /* Body of RPC call */ 181 struct call_body { 182 unsigned int rpcvers; 183 unsigned int prog; 184 unsigned int vers; 185 unsigned int proc; 186 opaque_auth cred; 187 opaque_auth verf; 189 /* procedure specific parameters start here */ 190 }; 191 /* Body of RPC reply */ 193 union reply_body switch (reply_stat stat) { 194 case MSG_ACCEPTED: 195 accepted_reply areply; 196 case MSG_DENIED: 197 rejected_reply rreply; 198 } reply; 200 /* Accepted reply */ 202 struct accepted_reply { 203 opaque_auth verf; 204 union switch (accept_stat stat) { 205 case SUCCESS: 206 opaque results[0]; 208 /* procedure-specific results start here */ 210 case PROG_MISMATCH: 211 struct { 212 unsigned int low; 213 unsigned int high; 214 } mismatch_info; 216 default: 218 /* 219 * Void. Cases include PROG_UNAVAIL, 220 * PROC_UNAVAIL, GARBAGE_ARGS, and 221 * SYSTEM_ERR. 222 */ 224 void; 225 } reply_data; 226 }; 228 /* Rejected reply */ 230 union rejected_reply switch (reject_stat stat) { 231 case RPC_MISMATCH: 232 struct { 233 unsigned int low; 234 unsigned int high; 235 } mismatch_info; 236 case AUTH_ERROR: 237 auth_stat stat; 238 }; 240 3. Flavor Number Assignment 242 The RPCSEC_GSS security flavor has been assigned the value of 6: 244 enum auth_flavor { 245 ... 246 RPCSEC_GSS = 6 /* RPCSEC_GSS security flavor */ 247 }; 249 4. New auth_stat Values 251 RPCSEC_GSS requires the addition of two new values to the auth_stat 252 enumerated type definition: 254 enum auth_stat { 255 ... 256 /* 257 * GSS related errors 258 */ 259 RPCSEC_GSS_NOCRED = 13, 260 RPCSEC_GSS_FAILED = 14 261 }; 262 The descriptions of these two new values are defined later in this 263 memo. 265 5. Elements of the RPCSEC_GSS Security Protocol 267 An RPC session based on the RPCSEC_GSS security flavor consists of 268 four phases: version negotiation, context creation, RPC data 269 exchange, and context destruction. In the following discussion, 270 protocol elements for these four phases are described. 272 The following description of the RPCSEC_GSS protocol uses some of the 273 definitions within XDR language description of the RPC protocol. 275 Version negotiation, context creation and destruction use control 276 messages that are not dispatched to service procedures registered by 277 an RPC server. The program and version numbers used in these control 278 messages are the same as the service program and version numbers. 279 The procedure number used is NULLPROC (zero). A field in the 280 credential information (the gss_proc field which is defined in the 281 rpc_gss_cred_t structure below) specifies whether a message is to be 282 interpreted as a control message or a regular RPC message. If this 283 field is set to RPCSEC_GSS_DATA, no control action is implied; in 284 this case, it is a regular data message. If this field is set to any 285 other value, a control action is implied. This is described in the 286 following sections. 288 Just as with normal RPC data exchange messages, the transaction 289 identifier (the xid field in struct rpc_msg), should be set to unique 290 values on each call for version negotiation, context creation, and 291 context destruction. 293 The following definitions are used for describing the protocol. 295 /* RPCSEC_GSS control procedures */ 297 #define RPCSEC_GSS_DATA 0 298 #define RPCSEC_GSS_INIT 1 299 #define RPCSEC_GSS_CONTINUE_INIT 2 300 #define RPCSEC_GSS_DESTROY 3 302 /* RPCSEC_GSS services */ 304 enum rpc_gss_service_t { 305 /* Note: the enumerated value for 0 is reserved. */ 306 rpc_gss_svc_none = 1, 307 rpc_gss_svc_integrity = 2, 308 rpc_gss_svc_privacy = 3 309 }; 311 /* Credential */ 313 #define RPCSEC_GSS_INQUIRE_VERS 0 /* version negotiation */ 314 #define RPCSEC_GSS_VERS_1 1 316 struct rpc_gss_cred_t { 317 union switch (unsigned int version) { /* version of RPCSEC_GSS */ 318 case RPCSEC_GSS_INQUIRE_VERS 319 struct { 320 unsigned int inquire_vers; 321 } rpc_gss_cred_vers_0_t; 323 case RPCSEC_GSS_VERS_1: 324 struct { 325 unsigned int gss_proc; /* control procedure */ 326 unsigned int seq_num; /* sequence number */ 327 rpc_gss_service_t service; /* service used */ 328 opaque handle<>; /* context handle */ 329 } rpc_gss_cred_vers_1_t; 330 } 331 }; 333 /* Maximum sequence number value */ 335 #define MAXSEQ 0x80000000 337 5.1. Version Negotiation 339 Before establishing a context, the RPC client needs to know which 340 version of the RPCSEC_GSS protocol the client and server both use. 341 Currently, aside from version zero (a control version) there is only 342 one version (RPCSEC_GSS_VERS_1), so this part of RPCSEC_GSS is 343 allowing for the possibility of future versions. 345 5.1.1. Version Inquiry Requests 347 The first RPC request from the client to the server inquires the 348 versions of RPCSEC_GSS supported on the server. Within the RPC 349 message protocol's call_body structure, rpcvers is set to 2. prog and 350 vers are always those for the service being accessed. The proc is 351 always set to NULLPROC (zero). 353 Within the RPC message protocol's cred structure, flavor is set to 354 RPCSEC_GSS (6). The opaque data of the cred structure (the body 355 field) constituting the credential encodes the rpc_gss_cred_t 356 structure defined previously. The version field of rpc_gss_cred_t 357 struct is set to RPCSEC_GSS_INQUIRE_VERS (zero). The inquire_vers 358 field is set to version of RPCSEC_GSS that the client wishes to use. 359 As is normal for NULLPROC requests, the call arguments are void. 361 5.1.2. Version Inquiry Responses 363 5.1.2.1. Normal Version Inquiry Responses 365 A normal response to a version inquiry request has the RPC message's 366 stat field in the reply_body set to an MSG_ACCEPTED response with a 367 status of SUCCESS. The verifier (the verf element in the response) 368 has the flavor field set to RPCSEC_GSS, and body field encodes the 369 following structure: 371 struct rpc_gss_vers_verf_t { 372 union switch (bool_t inquire_vers_supported) 373 case TRUE: 374 void; 375 case FALSE: 376 bool_t inquire_vers_in_hole; 377 unsigned int low; 378 unsigned int high; 379 }; 381 The server must use the following algorithm to compute the contents 382 of the verifier: 384 if (version in credential is one of server's supported versions) { 385 inquire_vers_supported = TRUE; 386 } else if (version < server's lowest supported version) { 387 inquire_vers_supported = FALSE; 388 inquire_vers_in_hole = FALSE; 389 low = server's lowest supported version; 390 high = server's highest support version; 391 } else if (version > server's highest supported version) { 392 inquire_vers_supported = FALSE; 393 inquire_vers_in_hole = FALSE; 394 low = server's lowest supported version; 395 high = server's highest supported version; 396 } else { 397 /* 398 * client has hit a "hole" in range of server's 399 * support versions 400 */ 402 inquire_vers_supported = FALSE; 403 inquire_vers_in_hole = TRUE; 405 low = server's highest supported version 406 that is < inquire_vers; 407 high = server's lowest supported version 408 that is > inquire_vers; 409 } 411 The server must never return values for low and high that are equal 412 to 0. As is normal for NULLPROC responses, the server must encode 413 void results after the verifier. 415 In the event inquire_vers_supported is FALSE, the client selects a 416 version it supports within the range specified by low and high, and 417 retries the version inquiry request. If there are holes 418 (inquire_vers_in_hole is set to FALSE) in range of versions the 419 server supports, the server effectively indicates the width of the 420 hole, by setting low and high to supported versions on the edges of 421 the hole. In the event the client has hit a hole, it is possible a 422 subsequent version inquiry request will return another mismatch 423 indication should the client try a version that is not equal to low 424 or high. The client and server can iterate to find a common version, 425 or until the client determines that it and the server have no common 426 version of the RPCSEC_GSS protocol. The client should initially be 427 optimistic and use the highest version of RPCSEC_GSS it supports when 428 setting the inquire_vers field in the version inquiry request. 429 Clients that support only one version will obviously have a trivial 430 implementation of the version inquiry protocol. 432 5.1.2.2. Abnormal Version Inquiry Responses 434 An MSG_ACCEPTED reply (to a version inquiry request) with an 435 acceptance status of other than SUCCESS has a NULL verifier (flavor 436 of AUTH_NONE and zero octets of data in the body field), and is 437 formulated as usual for different status values. 439 An MSG_DENIED reply (to a version inquiry request) is also formulated 440 as usual. Note that MSG_DENIED could be returned because the 441 server's RPC implementation does not recognize the RPCSEC_GSS 442 security flavor. RFC 1831 does not specify the appropriate reply 443 status in the general case of an unsupported security flavor. The 444 recommended for implementations of RPC that don't support a flavor is 445 a rejection status of AUTH_ERROR with an auth_stat of 446 AUTH_REJECTEDCRED. So RPC clients making RPCSEC_GSS version inquiry 447 requests should be prepared for AUTH_ERROR/AUTH_REJECTED responses. 448 Even though two new values (RPCSEC_GSS_NOCRED and RPCSEC_GSS_FAILED) 449 have been defined for the auth_stat type, neither of these two can be 450 returned in responses to version inquiry requests. The new values 451 are relevant to for responses to normal (data) requests. This is 452 described later. 454 5.1.2.3. Version Negotiation Examples 456 In following examples, the prefix "inquire_" for fields of the 457 rpc_gss_cred_vers_0_t and rpc_gss_vers_verf_t structures has been 458 stripped for clarity. 460 Example 1: Client supports version 2; 461 server supports versions 1,2,3. 463 Client Server 465 vers = 2 466 ---------------> 467 vers_supported = TRUE 468 <--------------- 470 Example 2: Client supports version 1,2; 471 server supports versions 1,3. 473 Client Server 475 vers = 2 476 ---------------> 477 vers_supported = FALSE 478 vers_in_hole = TRUE 479 low = 1, high = 3 480 <--------------- 482 Client knows that server supports version 1, so no more 483 version handshake messages are necessary. 485 Example 3: Client supports version 1,2,4; 486 server supports versions 1,3,5. 488 Client Server 490 vers = 4 491 ---------------> 492 vers_supported = FALSE 493 vers_in_hole = TRUE 494 low = 3, high = 5 495 <--------------- 496 vers = 2 497 ---------------> 498 vers_supported = FALSE 499 vers_in_hole = TRUE 500 low = 1, high = 3 501 <--------------- 503 Client knows that server supports version 1, so no more 504 version handshake messages are necessary. 506 5.2. Context Creation 508 Before RPC data is exchanged on a session using the RPCSEC_GSS 509 flavor, a context must be set up between the client and the server. 510 Context creation may involve zero or more RPC exchanges. The number 511 of exchanges depends on the security mechanism. 513 5.2.1. Context Creation Requests 515 The first RPC request from the client to the server initiates context 516 creation for those mechanisms that require context creation messages. 517 Within the RPC message protocol's call_body structure, rpcvers is set 518 to 2. prog and vers are always those for the service being accessed. 519 The proc is always set to NULLPROC (zero). 521 Within the RPC message protocol's cred structure, flavor is set to 522 RPCSEC_GSS (6). The opaque data of the cred structure (the body 523 field) constituting the credential encodes the rpc_gss_cred_t 524 structure defined previously. 526 The values of the fields contained in the rpc_gss_cred_t structure 527 are set as follows. The version field is set to the version of the 528 RPCSEC_GSS protocol that was determined in the version negotiation 529 phase. The remainder of this memo documents version 530 RPCSEC_GSS_VERS_1 of RPCSEC_GSS, and so the version field would be 531 set to RPCSEC_GSS_VERS_1. The gss_proc field must be set to 532 RPCSEC_GSS_INIT for the first creation request. In subsequent 533 creation requests, the gss_proc field must be set to 534 RPCSEC_GSS_CONTINUE_INIT. In a creation request, the seq_num and 535 service fields are undefined and both must be ignored by the server. 536 In the first creation request, the handle field is NULL (opaque data 537 of zero length). In subsequent creation requests, handle must be 538 equal to the value returned by the server. The handle field serves 539 as the identifier for the context, and will not change for the 540 duration of the context, including responses to 541 RPCSEC_GSS_CONTINUE_INIT. 543 The verifier field in the RPC message header is also described by the 544 opaque_auth structure. All creation requests have the NULL verifier 545 (AUTH_NONE flavor with zero length opaque data). 547 Following the verifier are the call data (procedure specific 548 parameters). Note that the proc field of the call_body structure is 549 set to NULLPROC, and thus normally there would be zero octets 550 following the verifier. However, since there is no RPC data exchange 551 during a context creation, it is safe to transfer information 552 following the verifier. It is necessary to "overload" the call data 553 in this way, rather than pack the GSS-API token into the RPC header, 554 because RPC Version 2 restricts the amount of data that can be sent 555 in the header. The opaque body of the credential and verifier fields 556 can be each at most 400 octets long, and GSS tokens can be longer 557 than 800 octets. 559 The call data for a context creation request is described by the 560 following structure for all creation requests: 562 struct rpc_gss_init_arg { 563 opaque gss_token<>; 564 unsigned int qop; 565 rpc_gss_service_t service; 566 }; 568 Here, gss_token is the token returned by the call to GSS-API's 569 gss_init_sec_context() routine, opaquely encoded. The value of this 570 field will likely be different in each creation request, if there is 571 more than one creation request. If no token is returned by the call 572 to gss_init_sec_context(), the context must have been created 573 (assuming no errors), and there will not be any more creation 574 requests. 576 The qop and service fields must be set to the GSS-API quality-of- 577 protection (QOP) and service the client wishes to use for the 578 session. Some services will need this information before they will 579 allow the context to be setup. Although the client can change the 580 QOP and service used on a per request basis, this may not be 581 acceptable to all RPC based services - such services may choose to 582 enforce the QOP and service specified during context creation for the 583 rest of the session. If there is more than one creation request, all 584 of them must use the same values for qop and service. 586 Note that QOPs are specific to the security mechanism that the call 587 to gss_init_sec_context() specified when the gss_token was created. 588 Because the specification in this memo is meant to be generic, this 589 memo does not specifically define valid QOPs. It is up to the 590 definers of GSS-API mechanisms to define valid QOPs. 592 5.2.2. Context Creation Responses 594 5.2.2.1. Context Creation Response - Successful Acceptance 596 The response to a successful creation request has an MSG_ACCEPTED 597 response with a status of SUCCESS. The results field encodes result 598 argument that has the following structure: 600 struct rpc_gss_init_res { 601 opaque handle<>; 602 unsigned int gss_major; 603 unsigned int gss_minor; 604 unsigned int seq_window; 605 opaque gss_token<>; 606 }; 608 Here, handle is non-NULL opaque data that serves as the context 609 identifier. The client must use this value in all subsequent requests 610 (whether control messages or otherwise). The server must generate 611 handles such that they will be generated again for the same pair of 612 client and server principals. Otherwise, the server could be 613 vulnerable to a replay attacker by an attacker that sends requests 614 from a previous context. The gss_major and gss_minor fields contain 615 the results of the call to gss_accept_sec_context() executed by the 616 server. If gss_major is not one of GSS_S_COMPLETE or 617 GSS_S_CONTINUE_NEEDED, the context setup has failed; in this case 618 handle and gss_token must be set to NULL by the server. The value of 619 gss_minor is dependent on the value of gss_major and the security 620 mechanism used. The gss_token field contains any token returned by 621 the gss_accept_sec_context() call executed by the server. A token 622 may be returned for both successful values of gss_major. If the 623 value is GSS_S_COMPLETE, it indicates that the server is not 624 expecting any more tokens, and the RPC Data Exchange phase must begin 625 on the subsequent request from the client. If the value is 626 GSS_S_CONTINUE_NEEDED, the server is expecting another token. Hence 627 the client must send at least one more creation request (with 628 gss_proc set to RPCSEC_GSS_CONTINUE_INIT in the request's credential) 629 carrying the required token. 631 In a successful response, the seq_window field is set to the sequence 632 window length supported by the server for this context. This window 633 specifies the maximum number of client requests that may be 634 outstanding for this context. The server will accept seq_window 635 requests at a time, and these may be out of order. The client may 636 use this number to determine the number of threads that can 637 simultaneously send requests on this context. 639 The verifier used for a successful context creation response is the 640 NULL verifier (AUTH_NONE flavor with zero-length opaque data). 642 5.2.2.1.1. Client Processing of Successful Context Creation Responses 644 If the value of gss_major in the response is GSS_S_CONTINUE_NEEDED, 645 then the client, per the GSS-API specification, must invoke 646 gss_init_sec_context() using the token returned in gss_token in the 647 context creation response. The client must then generate a context 648 creation request, with gss_proc set to RPCSEC_GSS_CONTINUE_INIT. 650 If the value of gss_major in the response is GSS_S_COMPLETE, and if 651 the client's previous invocation of gss_init_sec_context() returned a 652 gss_major value of GSS_S_CONTINUE_NEEDED, then the client, per the 653 GSS-API specification, must invoke gss_init_sec_context() using the 654 token returned in gss_token in the context creation response. If 655 gss_init_sec_context() returns GSS_S_COMPLETE, the context is 656 successfully set up, and the RPC data exchange phase must begin on 657 the subsequent request from the client. 659 5.2.2.2. Context Creation Response - Unsuccessful Cases 661 An MSG_ACCEPTED reply (to a creation request) with an acceptance 662 status of other than SUCCESS has a NULL verifier (flavor set to 663 AUTH_NONE, and zero length opaque data in the body field), and is 664 formulated as usual for different status values. 666 An MSG_DENIED reply (to a creation request) is also formulated as 667 usual. Note that MSG_DENIED could be returned because the server's 668 RPC implementation does not recognize the RPCSEC_GSS security flavor. 669 RFC 1831 does not specify the appropriate reply status in this 670 instance. Solaris 2 implementations return a rejection status of 671 AUTH_ERROR with an auth_stat of AUTH_REJECTEDCRED. Even though two 672 new values (RPCSEC_GSS_NOCRED and RPCSEC_GSS_FAILED) have been 673 defined for the auth_stat type, neither of these two can be returned 674 in responses to context creation requests. The new values are 675 relevant to for responses to normal (data) requests. This is 676 described later. 678 MSG_DENIED might also be returned if the RPCSEC_GSS version number in 679 the credential is not supported on the server. In the case, the 680 server returns a rejection status of AUTH_ERROR, with an auth_stat of 681 AUTH_REJECTED_CRED. 683 5.3. RPC Data Exchange 685 The data exchange phase is entered after a context has been 686 successfully set up. The format of the data exchanged depends on the 687 security service used for the request. Although clients can change 688 the security service and QOP used on a per-request basis, this may 689 not be acceptable to all RPC services. For all three modes of 690 service (no data integrity, data integrity, data privacy), the RPC 691 request header has the same format. 693 5.3.1. RPC Request Header 695 The credential has the opaque_auth structure described earlier. The 696 flavor field is set to RPCSEC_GSS. The credential body is created by 697 XDR encoding the rpc_gss_cred_t structure listed earlier into an 698 octet stream, and then opaquely encoding this octet stream as the 699 body field. 701 Values of the fields contained in the rpc_gss_cred_t structure are 702 set as follows. The version field is set to same version value that 703 was used to create the context, which within the scope of this memo 704 will always be RPCSEC_GSS_VERS_1. The gss_proc field is set to 705 RPCSEC_GSS_DATA. The service field is set to indicate the desired 706 service (one of rpc_gss_svc_none, rpc_gss_svc_integrity, or 707 rpc_gss_svc_privacy). The handle field is set to the context handle 708 value received from the RPC server during context creation. The 709 seq_num field can start at any value below MAXSEQ, and must be 710 incremented (by one or more) for successive requests. Use of 711 sequence numbers is described in detail when server processing of the 712 request is discussed. 714 The verifier has the opaque_auth structure described earlier. The 715 flavor field is set to RPCSEC_GSS. The body field is set as follows. 716 The checksum of the RPC header (up to and including the credential) 717 is computed using the gss_sign() call with the desired QOP. This 718 returns the checksum as an opaque octet stream and its length. This 719 is encoded into the body field. Note that the QOP is not explicitly 720 specified anywhere in the request. It is implicit in the checksum or 721 encrypted data. The same QOP value as is used for the header 722 checksum must also be used for the data (for checksumming or 723 encrypting), unless the service used for the request is 724 rpc_gss_svc_none. 726 5.3.2. RPC Request Data 728 5.3.2.1. RPC Request Data - No Data Integrity 730 If the service specified is rpc_gss_svc_none, the data (procedure 731 arguments) are not integrity or privacy protected. They are sent in 732 exactly the same way as they would be if the AUTH_NONE flavor were 733 used (following the verifier). Note, however, that since the RPC 734 header is integrity protected, the sender will still be authenticated 735 in this case. 737 5.3.2.2. RPC Request Data - With Data Integrity 739 When data integrity is used, the request data is represented as 740 follows: 742 struct rpc_gss_integ_data { 743 opaque databody_integ<>; 744 opaque checksum<>; 745 }; 747 The databody_integ field is created as follows. A structure 748 consisting of a sequence number followed by the procedure arguments 749 is constructed. This is shown below as the type rpc_gss_data_t: 751 struct rpc_gss_data_t { 752 unsigned int seq_num; 753 proc_req_arg_t arg; 754 }; 756 Here, seq_num must have the same value as in the credential. The 757 type proc_req_arg_t is the procedure specific XDR type describing the 758 procedure arguments (and so is not specified here). The octet stream 759 corresponding to the XDR encoded rpc_gss_data_t structure and its 760 length are placed in the databody_integ field. Note that because the 761 XDR type of databody_integ is opaque, the XDR encoding of 762 databody_integ will include an initial four octet length field, 763 followed by the XDR encoded octet stream of rpc_gss_data_t. 765 The checksum field represents the checksum of the XDR encoded octet 766 stream corresponding to the XDR encoded rpc_gss_data_t structure 767 (note, this is not the checksum of the databody_integ field). This 768 is obtained using the gss_sign() call, with the same QOP as was used 769 to compute the header checksum (in the verifier). The gss_sign() call 770 returns the checksum as an opaque octet stream and its length. The 771 checksum field of struct rpc_gss_integ_data has an XDR type of 772 opaque. Thus the checksum length from gss_sign() is encoded as a four 773 octet length field, followed by the checksum, padded to a multiple 774 of four octets. 776 5.3.2.3. RPC Request Data - With Data Privacy 778 When data privacy is used, the request data is represented as 779 follows: 781 struct rpc_gss_priv_data { 782 opaque databody_priv<> 783 }; 785 The databody_priv field is created as follows. The rpc_gss_data_t 786 structure described earlier is constructed again in the same way as 787 for the case of data integrity. Next, the gss_seal() call is invoked 788 to encrypt the octet stream corresponding to the rpc_gss_data_t 789 structure, using the same value for QOP as was used for the header 790 checksum (in the verifier). The gss_seal() call returns an opaque 791 octet stream (representing the encrypted rpc_gss_data_t structure) 792 and its length, and this is encoded as the databody_priv field. Since 793 databody_priv has an XDR type of opaque, the length returned by 794 gss_seal() is encoded as the four octet length, followed by the 795 encrypted octet stream (padded to a multiple of four octets). 797 5.3.3. Server Processing of RPC Data Requests 799 5.3.3.1. Context Management 801 When a request is received by the server, the following are verified 802 to be acceptable: 804 * the version number in the credential 806 * the service specified in the credential 808 * the context handle specified in the credential 810 * the header checksum in the verifier 812 * the sequence number (seq_num) specified in the credential (more 813 on this follows) 815 The gss_proc field in the credential must be set to RPCSEC_GSS_DATA 816 for data requests (otherwise, the message will be interpreted as a 817 control message). 819 The server maintains a window of "seq_window" sequence numbers, 820 starting with the last sequence number seen and extending backwards. 821 If a sequence number higher than the last number seen is received, 822 the window is moved forward to the new sequence number. If the last 823 sequence number seen is N, the server is prepared to receive requests 824 with sequence numbers in the range N through (N - seq_window + 1), 825 both inclusive. If the sequence number received falls below this 826 range, it is silently discarded. If the sequence number is within 827 this range, and the server has not seen it, the request is accepted, 828 and the server turns on a bit to "remember" that this sequence number 829 has been seen. If the server determines that it has already seen a 830 sequence number within the window, the request is silently discarded. 831 The server should select a seq_window value based on the number 832 requests it expects to process simultaneously. For example, in a 833 threaded implementation seq_window might be equal to the number of 834 server threads. There are no known security issues with selecting a 835 large window. The primary issue is how much space the server is 836 willing to allocate to keep track of requests received within the 837 window. 839 The reason for discarding requests silently is that the server is 840 unable to determine if the duplicate or out of range request was due 841 to a sequencing problem in the client, network, or the operating 842 system, or due to some quirk in routing, or a replay attack by an 843 intruder. Discarding the request allows the client to recover after 844 timing out, if indeed the duplication was unintentional or well 845 intended. Note that a consequence of the silent discard is that 846 clients may increment the seq_num by more than one. The effect of 847 this is that the window will move forward more quickly. It is not 848 believed that there is any benefit to doing this. 850 Note that the sequence number algorithm requires that the client 851 increment the sequence number even if it is retrying a request with 852 the same RPC transaction identifier. It is not infrequent for 853 clients to get into a situation where they send two or more attempts 854 and a slow server sends the reply for the first attempt. With 855 RPCSEC_GSS, each request and reply will have a unique sequence 856 number. If the client wishes to improve turn around time on the RPC 857 call, it can cache the RPCSEC_GSS sequence number of each request it 858 sends. Then when it receives a response with a matching RPC 859 transaction identifier, it can compute the checksum of each sequence 860 number in the cache to try to match the checksum in the reply's 861 verifier. 863 The data is decoded according to the service specified in the 864 credential. In the case of integrity or privacy, the server ensures 865 that the QOP value is acceptable, and that it is the same as that 866 used for the header checksum in the verifier. Also, in the case of 867 integrity or privacy, the server will reject the message (with a 868 reply status of MSG_ACCEPTED, and an acceptance status of 869 GARBAGE_ARGS) if the sequence number embedded in the request body is 870 different from the sequence number in the credential. 872 5.3.3.2. Server Reply - Request Accepted 874 An MSG_ACCEPTED reply to a request in the data exchange phase will 875 have the verifier's (the verf element in the response) flavor field 876 set to RPCSEC_GSS, and the body field set to the checksum of the 877 sequence number (in network order) of the corresponding request. The 878 QOP used is the same as the QOP used for the corresponding request. 880 If the status of the reply is not SUCCESS, the rest of the message is 881 formatted as usual. 883 If the status of the message is SUCCESS, the format of the rest of 884 the message depends on the service specified in the corresponding 885 request message. Basically, what follows the verifier in this case 886 are the procedure results, formatted in different ways depending on 887 the requested service. 889 If no data integrity was requested, the procedure results are 890 formatted as for the AUTH_NONE security flavor. 892 If data integrity was requested, the results are encoded in exactly 893 the same way as the procedure arguments were in the corresponding 894 request. See the section 'RPC Request Data - With Data Integrity.' 895 The only difference is that the structure representing the 896 procedure's result - proc_res_arg_t - must be substituted in place of 897 the request argument structure proc_req_arg_t. The QOP used for the 898 checksum must be the same as that used for constructing the reply 899 verifier. 901 If data privacy was requested, the results are encoded in exactly the 902 same way as the procedure arguments were in the corresponding 903 request. See the section 'RPC Request Data - With Data Privacy.' 904 The QOP used for encryption must be the same as that used for 905 constructing the reply verifier. 907 5.3.3.3. Server Reply - Request Denied 909 An MSG_DENIED reply (to a data request) is formulated as usual. Two 910 new values (RPCSEC_GSS_NOCRED and RPCSEC_GSS_FAILED) have been 911 defined for the auth_stat type. When the reason for denial of the 912 request is a reject_stat of AUTH_ERROR, one of the two new auth_stat 913 values could be returned in addition to the existing values. These 914 two new values have special significance from the existing reasons 915 for denial of a request. 917 The server maintains a list of contexts for the clients that are 918 currently in session with it. Normally, a context is destroyed when 919 the client ends the session corresponding to it. However, due to 920 resource constraints, the server may destroy a context prematurely 921 (on an LRU basis, or if the server machine is rebooted, for example). 922 In this case, when a client request comes in, there may not be a 923 context corresponding to its handle. The server rejects the request, 924 with the reason RPCSEC_GSS_NOCRED in this case. Upon receiving this 925 error, the client must refresh the context - that is, reestablish it 926 after destroying the old one - and try the request again. This error 927 is also returned if the context handle matches that of a different 928 context that was allocated after the client's context was destroyed 929 (this will be detected by a failure in verifying the header 930 checksum). 932 When the client's sequence number exceeds the maximum the server will 933 allow, the server will reject the request with the reason 934 RPCSEC_GSS_FAILED. Also, if security credentials become stale while 935 in use (due to ticket expiry in the case of the Kerberos V5 936 mechanism, for example), the failures which result cause the 937 RPCSEC_GSS_FAILED reason to be returned. In these cases also, the 938 client must refresh the context, and retry the request. 940 For other errors, retrying will not rectify the problem and the 941 client must not refresh the context until the problem causing the 942 client request to be denied is rectified. 944 If the version field in the credential does not match the version of 945 RPCSEC_GSS that was used when the context was created, the 946 AUTH_BADCRED value is returned. 948 If there is a problem with the credential, such a bad length, illegal 949 control procedure, or an illegal service, the appropriate auth_stat 950 status is AUTH_BADCRED. 952 Other errors can be returned as appropriate. 954 5.4. Context Destruction 956 When the client is done using the session, it must send a control 957 message informing the server that it no longer requires the context. 958 This message is formulated just like a data request packet, with the 959 following differences: the credential has gss_proc set to 960 RPCSEC_GSS_DESTROY, the procedure specified in the header is 961 NULLPROC, and there are no procedure arguments. The sequence number 962 in the request must be valid, and the header checksum in the verifier 963 must be valid, for the server to accept the message. 965 The server sends a response as it would to a data request. The 966 client and server must then destroy the context for the session. 968 If the request to destroy the context fails for some reason, the 969 client need not take any special action. The server must be prepared 970 to deal with situations where clients never inform the server that 971 they no longer are in session and so don't need the server to 972 maintain a context. An LRU mechanism or an aging mechanism should be 973 employed by the server to clean up in such cases. 975 6. Security Considerations 977 6.1. Privacy of Call Header 979 The reader will note that for the privacy option, only the call 980 arguments and results are encrypted. Information about the 981 application in the form of RPC program number, program version 982 number, and program procedure number is transmitted in the clear. 983 Encrypting these fields in the RPC call header would have changed the 984 size and format of the call header. This would have required revising 985 the RPC protocol which was beyond the scope of this proposal. Storing 986 the encrypted numbers in the credential would have obviated a 987 protocol change, but would have introduced more overloading of fields 988 and would have made implementations of RPC more complex. Even if the 989 fields were encrypted somehow, in most cases an attacker can 990 determine the program number and version number by examining the 991 destination address of the request and querying the rpcbind service 992 on the destination host [Srinivasan-bind]. In any case, even by not 993 encrypting the three numbers, RPCSEC_GSS still improves the state of 994 security over what existing RPC services have had available 995 previously. Implementors of new RPC services that are concerned about 996 this risk may opt to design in a "sub-procedure" field that is 997 included in the service specific call arguments. 999 6.2. Sequence number attacks 1001 An attacker cannot coax the server into raising the sequence number 1002 beyond the range the legitimate client is aware of (and thus engineer 1003 a denial of server attack) without constructing an RPC request that 1004 will pass the header checksum. If the cost of verifying the header 1005 checksum is sufficiently large (depending on the speed of the 1006 processor doing the checksum and the cost of checksum algorithm), it 1007 is possible to envision a denial of service attack whereby the 1008 attacker sends requests that are outside the window. The most trivial 1009 one, would be one where the attacker sends a request with a sequence 1010 number that is below the window. In this case, even if the header 1011 checksum were successfully verified, the server would silently 1012 discard it. To guard against this kind of denial of service (stealing 1013 processing resources), one might implement a server to examine a 1014 request's sequence number to see if it is below the window before 1015 verifying the checksum. 1017 6.3. Message stealing attacks 1019 This proposal does not address attacks where an attacker can block or 1020 steal messages without being detected by the server. To implement 1021 such protection would be tantamount to assuming a state in the RPC 1022 service. RPCSEC_GSS does not worsen this situation. 1024 7. Acknowledgements 1026 Much of protocol was based on the AUTH_GSSAPI security flavor 1027 developed by Open Vision Technologies [Jaspan]. In particular, we 1028 acknowledge Barry Jaspan, Marc Horowitz, John Linn, and Ellen 1029 McDermott. 1031 Raj Srinivasan designed RPCSEC_GSS [Eisler] with input from Mike 1032 Eisler. Raj, Roland Schemers, Lin Ling, and Alex Chiu contributed to 1033 SunSoft's implementation of RPCSEC_GSS. 1035 Brent Callaghan, Barry Jaspan, Marc Horowitz, Hilarie Orman, Martin 1036 Rex, and John Wroclawski analyzed the specification and gave valuable 1037 feedback. 1039 Steve Nahm, Kathy Slattery, and Brent Callaghan reviewed various 1040 drafts of this specification. 1042 8. References 1044 [Eisler] Eisler, M., Schemers, R., and Srinivasan, R. (1996). 1045 "Security Mechanism Independence in ONC RPC," To be 1046 published in the Proceedings of 1996 Usenix Security 1047 Symposium. 1049 [Jaspan] Jaspan, B. (1995). "GSS-API Security for ONC RPC," 1050 `95 Proceedings of The Internet Society Symposium on 1051 Network and Distributed System Security, pp. 144- 1052 151. 1054 [Linn] Linn, J. (1993). RFC 1508, "Generic Security Service 1055 Application Program Interface." 1057 [Srinivasan-bind] Srinivasan, R. (1995). RFC 1833, "Binding Protocols 1058 for ONC RPC Version 2." 1060 [Srinivasan-rpc] Srinivasan, R. (1995). RFC 1831, "RPC: Remote 1061 Procedure Call Protocol Specification Version 2." 1063 [Srinivasan-xdr] Srinivasan, R. (1995). RFC 1832, "XDR: External Data 1064 Representation Standard." 1066 9. Authors' Addresses 1068 Michael Eisler 1069 Sun Microsystems, Inc. 1070 M/S UCOS03 1071 2550 Garcia Avenue 1072 Mountain View, CA 94043 1074 Phone: +1 (719) 599-9026 1076 E-mail: mre@eng.sun.com 1078 Alex Chiu 1079 Sun Microsystems, Inc. 1080 M/S UMPK17-203 1081 2550 Garcia Avenue 1082 Mountain View, CA 94043 1084 Phone: +1 (415) 786-6465 1086 E-mail: hacker@eng.sun.com 1088 Lin Ling 1089 Sun Microsystems, Inc. 1090 M/S UMPK17-201 1091 2550 Garcia Avenue 1092 Mountain View, CA 94043 1094 Phone: +1 (415) 786-5084 1096 E-mail: lling@eng.sun.com