idnits 2.17.1 draft-ietf-oncrpc-rpcsec_gss-00.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-20) 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-oncrpc-rpcsec_gss-00', contains other characters than digits, lowercase letters and dash. == Mismatching filename: the document gives the document name as 'draft-oncrpc-rpcsec_gss-00', but the file name used is 'draft-ietf-oncrpc-rpcsec_gss-00' == 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 is 1 instance of too long lines in the document, the longest one being 3 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 178 has weird spacing: '...ue_auth cred;...' == Line 179 has weird spacing: '...ue_auth verf;...' == Line 701 has weird spacing: '... octet lengt...' == Line 832 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 (22 July 1996) is 10134 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 200 -- 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 (~~), 7 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 ONC RPC Working Group M. Eisler 2 Internet Draft A. Chiu 3 Document: draft-oncrpc-rpcsec_gss-00.txt L. Ling 4 22 July 1996 6 RPCSEC_GSS Protocol Specification 8 Abstract 10 This memo describes an ONC/RPC security flavor that allows RPC 11 protocols to access the Generic Security Services Application 12 Programming Interface (referred to henceforth as GSS-API). 14 Status of this Memo 16 This document is an Internet-Draft. Internet-Drafts are working 17 documents of the Internet Engineering Task Force (IETF), its areas, 18 and its working groups. Note that other groups may also distribute 19 working documents as Internet-Drafts. 21 Internet-Drafts are draft documents valid for a maximum of six 22 months. This Internet-Draft expires on January 22, 1997. Internet- 23 Drafts may be updated, replaced, or obsoleted by other documents at 24 any time. It is not appropriate to use Internet-Drafts as reference 25 material or to cite them other than as "work in progress." 27 To learn the current status of any Internet-Draft, please check the 28 "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow 29 Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe), 30 munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or 31 ftp.isi.edu (US West Coast). 33 Distribution of this memo is unlimited. 35 Table of Contents 37 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2 38 2. Review of the RPC Message Protocol . . . . . . . . . . . . . . 2 39 3. Flavor number assignment . . . . . . . . . . . . . . . . . . . 5 40 4. New auth_stat values . . . . . . . . . . . . . . . . . . . . . 6 41 5. Elements of the RPCSEC_GSS Security Protocol . . . . . . . . . 6 42 5.1. Version Negotiation . . . . . . . . . . . . . . . . . . . . 7 43 5.1.1. Version Inquiry Requests . . . . . . . . . . . . . . . . . 7 44 5.1.2. Version Inquiry Responses . . . . . . . . . . . . . . . . 8 45 5.1.2.1. Normal Version Inquiry Responses . . . . . . . . . . . . 8 46 5.1.2.2. Abnormal Version Inquiry Responses . . . . . . . . . . . 9 47 5.2. Context Creation . . . . . . . . . . . . . . . . . . . . . 10 48 5.2.1. Context Creation Requests . . . . . . . . . . . . . . . 10 49 5.2.2. Context Creation Responses . . . . . . . . . . . . . . . 11 50 5.2.2.1. Context Creation Response - Successful Acceptance . . 11 51 5.2.2.1.1. Client Processing of Successful Context Creation 52 Responses . . . . . . . . . . . . . . . . . . . . . 12 53 5.2.2.2. Context Creation Response - Unsuccessful Cases . . . . 13 54 5.3. RPC Data Exchange . . . . . . . . . . . . . . . . . . . . 13 55 5.3.1. RPC Request Header . . . . . . . . . . . . . . . . . . . 13 56 5.3.2. RPC Request Data . . . . . . . . . . . . . . . . . . . . 14 57 5.3.2.1. RPC Request Data - No Data Integrity . . . . . . . . . 14 58 5.3.2.2. RPC Request Data - With Data Integrity . . . . . . . . 14 59 5.3.2.3. RPC Request Data - With Data Privacy . . . . . . . . . 15 60 5.3.3. Server Processing of RPC Data Requests . . . . . . . . . 16 61 5.3.3.1. Context Management . . . . . . . . . . . . . . . . . . 16 62 5.3.3.2. Server Reply - Request Accepted . . . . . . . . . . . 17 63 5.3.3.3. Server Reply - Request Denied . . . . . . . . . . . . 18 64 5.4. Context Destruction . . . . . . . . . . . . . . . . . . . 19 65 6. Security Considerations . . . . . . . . . . . . . . . . . . 19 66 6.1. Privacy of Call Header . . . . . . . . . . . . . . . . . . 19 67 6.2. Sequence number attacks . . . . . . . . . . . . . . . . . 20 68 6.3. Message stealing attacks . . . . . . . . . . . . . . . . . 20 69 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 20 70 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 21 71 9. Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 21 73 1. Introduction 75 This document describes the protocol used by the RPCSEC_GSS security 76 flavor. Security flavors have been called authentication flavors for 77 historical reasons. This memo recognizes that there are two other 78 security services besides authentication, integrity, and privacy, and 79 so defines a new RPCSEC_GSS security flavor. 81 The protocol is described using the XDR language [Srinivasan-xdr]. 82 The reader is assumed to be familiar with ONC RPC and the security 83 flavor mechanism [Srinivasan-rpc]. The reader is also assumed to be 84 familiar with the GSS-API framework [Linn]. The RPCSEC_GSS security 85 flavor uses GSS-API interfaces to provide security services that are 86 independent of the underlying security mechanism. 88 2. Review of the RPC Message Protocol 90 This memo refers to several fields of the RPC protocol. For 91 convenience, the XDR language description of the RPC message protocol 92 is reproduced here. 94 /* RPC message type */ 95 enum msg_type { 96 CALL = 0, 97 REPLY = 1 98 }; 100 /* Reply types */ 102 enum reply_stat { 103 MSG_ACCEPTED = 0, 104 MSG_DENIED = 1 105 }; 107 /* Security flavors */ 109 enum auth_flavor { 110 AUTH_NONE = 0, 111 AUTH_SYS = 1, 112 AUTH_SHORT = 2 113 }; 115 /* Status of accepted messages */ 117 enum accept_stat { 118 SUCCESS = 0, 119 PROG_UNAVAIL = 1, 120 PROG_MISMATCH = 2, 121 PROC_UNAVAIL = 3, 122 GARBAGE_ARGS = 4, 123 SYSTEM_ERR = 5 124 }; 126 /* Status of rejected messages */ 128 enum reject_stat { 129 RPC_MISMATCH = 0, 130 AUTH_ERROR = 1 131 }; 133 /* Why authentication failed */ 135 enum auth_stat { 136 AUTH_OK = 0, 138 /* failed at remote end */ 140 AUTH_BADCRED = 1, 141 AUTH_REJECTEDCRED = 2, 142 AUTH_BADVERF = 3, 143 AUTH_REJECTEDVERF = 4, 144 AUTH_TOOWEAK = 5, 146 /* failed locally */ 148 AUTH_INVALIDRESP = 6, 149 AUTH_FAILED = 7 150 }; 152 /* Opaque structure of credential and verifier */ 154 struct opaque_auth { 155 auth_flavor flavor; 156 opaque body<400>; 157 }; 159 /* The RPC message */ 161 struct rpc_msg { 162 unsigned int xid; 163 union switch (msg_type mtype) { 164 case CALL: 165 call_body cbody; 166 case REPLY: 167 reply_body rbody; 168 } body; 169 }; 171 /* Body of RPC call */ 173 struct call_body { 174 unsigned int rpcvers; 175 unsigned int prog; 176 unsigned int vers; 177 unsigned int proc; 178 opaque_auth cred; 179 opaque_auth verf; 181 /* procedure specific parameters start here */ 182 }; 184 /* Body of RPC reply */ 186 union reply_body switch (reply_stat stat) { 187 case MSG_ACCEPTED: 188 accepted_reply areply; 189 case MSG_DENIED: 190 rejected_reply rreply; 192 } reply; 194 /* Accepted reply */ 196 struct accepted_reply { 197 opaque_auth verf; 198 union switch (accept_stat stat) { 199 case SUCCESS: 200 opaque results[0]; 202 /* procedure-specific results start here */ 204 case PROG_MISMATCH: 205 struct { 206 unsigned int low; 207 unsigned int high; 208 } mismatch_info; 210 default: 212 /* 213 * Void. Cases include PROG_UNAVAIL, 214 * PROC_UNAVAIL, GARBAGE_ARGS, and 215 * SYSTEM_ERR. 216 */ 218 void; 219 } reply_data; 220 }; 222 /* Rejected reply */ 224 union rejected_reply switch (reject_stat stat) { 225 case RPC_MISMATCH: 226 struct { 227 unsigned int low; 228 unsigned int high; 229 } mismatch_info; 230 case AUTH_ERROR: 231 auth_stat stat; 232 }; 234 3. Flavor number assignment 236 The RPCSEC_GSS security flavor has been assigned the value of 6: 238 enum auth_flavor { 239 ... 241 RPCSEC_GSS = 6 /* RPCSEC_GSS security flavor */ 242 }; 244 4. New auth_stat values 246 RPCSEC_GSS requires the addition of two new values to the auth_stat 247 enumerated type definition: 249 enum auth_stat { 250 ... 251 /* 252 * GSS related errors 253 */ 254 RPCSEC_GSS_NOCRED = 13, 255 RPCSEC_GSS_FAILED = 14 256 }; 257 The descriptions of these two new values are defined later in this 258 memo. 260 5. Elements of the RPCSEC_GSS Security Protocol 262 An RPC session based on the RPCSEC_GSS security flavor consists of 263 four phases: version negotiation, context creation, RPC data 264 exchange, and context destruction. In the following discussion, 265 protocol elements for these four phases are described. 267 The following description of the RPCSEC_GSS protocol uses some of the 268 definitions within XDR language description of the RPC protocol. 270 Version negotiation, context creation and destruction use control 271 messages that are not dispatched to service procedures registered by 272 an RPC server. The program and version numbers used in these control 273 messages are the same as the service program and version numbers. 274 The procedure number used is NULLPROC (zero). A field in the 275 credential information (the gss_proc field) specifies whether a 276 message is to be interpreted as a control message or a regular RPC 277 message. If this field is set to RPCSEC_GSS_DATA, no control action 278 is implied; in this case, it is a regular data message. If this 279 field is set to any other value, a control action is implied. This 280 is described in the following sections. 282 The following definitions are used for describing the protocol. 284 /* RPCSEC_GSS control procedures */ 286 #define RPCSEC_GSS_DATA 0 287 #define RPCSEC_GSS_INIT 1 288 #define RPCSEC_GSS_CONTINUE_INIT 2 289 #define RPCSEC_GSS_DESTROY 3 291 /* RPCSEC_GSS services */ 293 enum rpc_gss_service_t { 294 /* Note: the enumerated value for 0 is reserved. */ 295 rpc_gss_svc_none = 1, 296 rpc_gss_svc_integrity = 2, 297 rpc_gss_svc_privacy = 3 298 }; 300 /* Credential */ 302 #define RPCSEC_GSS_INQUIRE_VERS 0 /* version negotiation */ 303 #define RPCSEC_GSS_VERS_1 1 305 struct rpc_gss_cred_t { 306 union switch (unsigned int version) { /* version of RPCSEC_GSS */ 307 case RPCSEC_GSS_INQUIRE_VERS 308 struct { 309 unsigned int inquire_vers; 310 } rpc_gss_cred_vers_0_t; 312 case RPCSEC_GSS_VERS_1: 313 struct { 314 unsigned int gss_proc; /* control procedure */ 315 unsigned int seq_num; /* sequence number */ 316 rpc_gss_service_t service; /* service used */ 317 opaque handle<>; /* context handle */ 318 } rpc_gss_cred_vers_1_t; 319 } 320 }; 322 /* Maximum sequence number value */ 324 #define MAXSEQ 0x80000000 326 5.1. Version Negotiation 328 Before establishing a context, the RPC client needs to know which 329 version of the RPCSEC_GSS protocol the client and server both use. 330 Currently, aside from version zero (a control version) there is only 331 one version (RPCSEC_GSS_VERS_1), so this part of RPCSEC_GSS is 332 allowing for the possibility of future versions. 334 5.1.1. Version Inquiry Requests 336 The first RPC request from the client to the server inquires the 337 versions of RPCSEC_GSS supported on the server. Within the RPC 338 message protocol's call_body structure, rpcvers is set to 2. prog and 339 vers are always those for the service being accessed. The proc is 340 always set to NULLPROC (zero). 342 Within the RPC message protocol's cred structure, flavor is set to 343 RPCSEC_GSS (6). The opaque data of the cred structure (the body 344 field) constituting the credential encodes the rpc_gss_cred_t 345 structured defined previously. The version field of rpc_gss_cred_t 346 struct is set to RPCSEC_GSS_INQUIRE_VERS (zero). The inquire_vers 347 field is set to version of RPCSEC_GSS that the client wishes to use. 348 inquire_ver must be equal to 1. As is normal for NULLPROC requests, 349 the call arguments are void. 351 5.1.2. Version Inquiry Responses 353 5.1.2.1. Normal Version Inquiry Responses 355 A normal response to a version inquiry request has the RPC message's 356 stat field in the reply_body set to an MSG_ACCEPTED response with a 357 status of SUCCESS. The verifier (the verf element in the response) 358 has the flavor field set to RPCSEC_GSS, and body field encodes the 359 following structure: 361 struct rpc_gss_vers_verf_t { 362 union switch (bool_t inquire_vers_supported) 363 case TRUE: 364 void; 365 case FALSE: 366 boot_t inquire_vers_in_hole; 367 unsigned int low; 368 unsigned int high; 369 }; 371 The server must use the following algorithm to compute the contents 372 of the verifier: 374 if (version in credential is one of server's supported versions) { 375 inquire_vers_supported = TRUE; 376 } else if (version < server's lowest supported version) { 377 inquire_vers_supported = FALSE; 378 inquire_vers_in_hole = FALSE; 379 low = server's lowest supported version; 380 high = server's highest support version; 381 } else if (version > server's highest supported version) { 382 inquire_vers_supported = FALSE; 383 inquire_vers_in_hole = FALSE; 384 low = server's lowest supported version; 385 high = server's highest supported version; 386 } else { 387 /* 388 * client has hit a "hole" in range of server's 389 * support versions 390 */ 392 inquire_vers_supported = FALSE; 393 inquire_vers_in_hole = TRUE; 394 low = server's highest supported version 395 that is < inquire_vers; 396 high = server's lowest supported version 397 that is > inquire_vers; 398 } 400 The server must never return values for low and high that are equal 401 to 0. As is normal for NULLPROC responses, the server must encode 402 void results after the verifier. 404 In the event inquire_ver_supported is FALSE, the client selects a 405 version it supports within the range specified by low and high, and 406 retries the version inquiry request. If there are holes in range of 407 versions the server supports, it is possible another mismatch 408 indication will be returned. The client and server can then iterate 409 to find a common version, or until the client determines that it and 410 the server have no common version of the RPCSEC_GSS protocol. The 411 client should initially be optimistic and use the highest version of 412 RPCSEC_GSS it supports when setting the inquire_vers field in the 413 version inquiry request. 415 5.1.2.2. Abnormal Version Inquiry Responses 417 An MSG_ACCEPTED reply (to a version inquiry request) with an 418 acceptance status of other than SUCCESS has a NULL verifier (flavor 419 of AUTH_NONE and zero octets of data in the body field), and is 420 formulated as usual for different status values. 422 An MSG_DENIED reply (to a version inquiry request) is also formulated 423 as usual. Note that MSG_DENIED could be returned because the 424 server's RPC implementation does not recognize the RPCSEC_GSS 425 security flavor. RFC 1831 does not specify the appropriate reply 426 status in this instance. Solaris 2 implementations return a 427 rejection status of AUTH_ERROR with an auth_stat of 428 AUTH_REJECTEDCRED. Even though two new values (RPCSEC_GSS_NOCRED and 429 RPCSEC_GSS_FAILED) have been defined for the auth_stat type, neither 430 of these two can be returned in responses to version inquiry 431 requests. The new values are relevant to for responses to normal 432 (data) requests. This is described later. 434 5.2. Context Creation 436 Before RPC data is exchanged on a session using the RPCSEC_GSS 437 flavor, a context must be set up between the client and the server. 438 Context creation may involve zero or more RPC exchanges. The number 439 of exchanges depends on the security mechanism. 441 5.2.1. Context Creation Requests 443 The first RPC request from the client to the server initiates context 444 creation for those mechanisms that require context creation messages. 445 Within the RPC message protocol's call_body structure, rpcvers is set 446 to 2. prog and vers are always those for the service being accessed. 447 The proc is always set to NULLPROC (zero). 449 Within the RPC message protocol's cred structure, flavor is set to 450 RPCSEC_GSS (6). The opaque data of the cred structure (the body 451 field) constituting the credential encodes the rpc_gss_cred_t 452 structured defined previously. 454 The values of the fields contained in the rpc_gss_cred_t structure 455 are set as follows. The version field is set to the version of the 456 RPCSEC_GSS protocol that was determined in the version negotiation 457 phase. The remainder of this memo documents version 458 RPCSEC_GSS_VERS_1 of RPCSEC_GSS, and so the version field would be 459 set to RPCSEC_GSS_VERS_1. The gss_proc field must be set to 460 RPCSEC_GSS_INIT for the first creation request. In subsequent 461 creation requests, the gss_proc field must be set to 462 RPCSEC_GSS_CONTINUE_INIT. In a creation request, the seq_num and 463 service fields are undefined and both must be ignored by the server. 464 In the first creation request, the handle field is NULL (opaque data 465 of zero length). In subsequent creation requests, handle must be 466 equal to the value returned by the server. The handle field serves 467 as the identifier for the context, and will not change for the 468 duration of the context, including responses to 469 RPCSEC_GSS_CONTINUE_INIT. 471 The verifier field in the RPC message header is also described by the 472 opaque_auth structure. All creation requests have the NULL verifier 473 (AUTH_NONE flavor with zero length opaque data). 475 Following the verifier are the call data (procedure specific 476 parameters). Note that the proc field of the call_body structure is 477 set to NULLPROC, and thus normally there would be zero octets 478 following the verifier. However, since there is no RPC data exchange 479 during a context creation, it is safe to transfer information 480 following the verifier. It is necessary to "overload" the call data 481 in this way, rather than pack the GSS-API token into the RPC header, 482 because RPC Version 2 restricts the amount of data that can be sent 483 in the header. The opaque body of the credential and verifier fields 484 can be each at most 400 octets long, and GSS tokens can be longer 485 than 800 octets. 487 The call data for a context creation request is described by the 488 following structure for all creation requests: 490 struct rpc_gss_init_arg { 491 opaque gss_token<>; 492 unsigned int qop; 493 rpc_gss_service_t service; 494 }; 496 Here, gss_token is the token returned by the call to GSS-API's 497 gss_init_sec_context() routine, opaquely encoded. The value of this 498 field will likely be different in each creation request, if there is 499 more than one creation request. If no token is returned by the call 500 to gss_init_sec_context(), the context must have been created 501 (assuming no errors), and there will not be any more creation 502 requests. 504 The qop and service fields must be set to the GSS-API quality-of- 505 protection (QOP) and service the client wishes to use for the 506 session. Some services will need this information before they will 507 allow the context to be setup. Although the client can change the 508 QOP and service used on a per request basis, this may not be 509 acceptable to all RPC based services - such services may choose to 510 enforce the QOP and service specified during context creation for the 511 rest of the session. If there is more than one creation request, all 512 of them must use the same values for qop and service. 514 Note that QOPs are specific to the security mechanism that the call 515 to gss_init_sec_context() specified when the gss_token was created. 516 Because the specification in this memo is meant to be generic, this 517 memo does not specifically define valid QOPs. It is up to the 518 definers of GSS-API mechanisms to define valid QOPs. 520 5.2.2. Context Creation Responses 522 5.2.2.1. Context Creation Response - Successful Acceptance 524 The response to a successful creation request has an MSG_ACCEPTED 525 response with a status of SUCCESS. The results field encodes result 526 argument that has the following structure: 528 struct rpc_gss_init_res { 529 opaque handle<>; 530 unsigned int gss_major; 531 unsigned int gss_minor; 532 unsigned int seq_window; 533 opaque gss_token<>; 534 }; 536 Here, handle is non-NULL opaque data that serves as the context 537 identifier. The client must use this value in all subsequent requests 538 (whether control messages or otherwise). The server must generate 539 handles such that they will be generated again for the same pair of 540 client and server principals. Otherwise, the server could be 541 vulnerable to a replay attacker by an attacker that sends requests 542 from a previous context. The gss_major and gss_minor fields contain 543 the results of the call to gss_accept_sec_context() executed by the 544 server. If gss_major is not one of GSS_S_COMPLETE or 545 GSS_S_CONTINUE_NEEDED, the context setup has failed; in this case 546 handle and gss_token must be set to NULL by the server. The value of 547 gss_minor is dependent on the value of gss_major and the security 548 mechanism used. The gss_token field contains any token returned by 549 the gss_accept_sec_context() call executed by the server. A token 550 may be returned for both successful values of gss_major. If the 551 value is GSS_S_COMPLETE, it indicates that the server is not 552 expecting any more tokens, and the RPC Data Exchange phase must begin 553 on the subsequent request from the client. If the value is 554 GSS_S_CONTINUE_NEEDED, the server is expecting another token. Hence 555 the client must send at least one more creation request (with 556 gss_proc set to RPCSEC_GSS_CONTINUE_INIT in the request's credential) 557 carrying the required token. 559 In a successful response, the seq_window field is set to the sequence 560 window length supported by the server for this context. This window 561 specifies the maximum number of client requests that may be 562 outstanding for this context. The server will accept seq_window 563 requests at a time, and these may be out of order. The client may 564 use this number to determine the number of threads that can 565 simultaneously send requests on this context. 567 The verifier used for a successful context creation response is the 568 NULL verifier (AUTH_NONE flavor with zero-length opaque data). 570 5.2.2.1.1. Client Processing of Successful Context Creation Responses 572 If the value of gss_major in the response is GSS_S_CONTINUE_NEEDED, 573 then the client, per the GSS-API specification, must invoke 574 gss_init_sec_context() using the token returned in gss_token in the 575 context creation response. The client must then generate a context 576 creation request, with gss_proc set to RPCSEC_GSS_CONTINUE_INIT. 578 If the value of gss_major in the response is GSS_S_COMPLETE, and if 579 the client's previous invocation of gss_init_sec_context() returned a 580 gss_major value of GSS_S_CONTINUE_NEEDED, then the client, per the 581 GSS-API specification, must invoke gss_init_sec_context() using the 582 token returned in gss_token in the context creation response. If 583 gss_init_sec_sec_context() returns GSS_S_COMPLETE, the context is 584 successfully set up, and the RPC data exchange phase must begin on 585 the subsequent request from the client. 587 5.2.2.2. Context Creation Response - Unsuccessful Cases 589 An MSG_ACCEPTED reply (to a creation request) with an acceptance 590 status of other than SUCCESS has a NULL verifier (flavor set to 591 AUTH_NONE, and zero length opaque data in the body field), and is 592 formulated as usual for different status values. 594 An MSG_DENIED reply (to a creation request) is also formulated as 595 usual. Note that MSG_DENIED could be returned because the server's 596 RPC implementation does not recognize the RPCSEC_GSS security flavor. 597 RFC 1831 does not specify the appropriate reply status in this 598 instance. Solaris 2 implementations return a rejection status of 599 AUTH_ERROR with an auth_stat of AUTH_REJECTEDCRED. Even though two 600 new values (RPCSEC_GSS_NOCRED and RPCSEC_GSS_FAILED) have been 601 defined for the auth_stat type, neither of these two can be returned 602 in responses to context creation requests. The new values are 603 relevant to for responses to normal (data) requests. This is 604 described later. 606 MSG_DENIED might also be returned if the RPCSEC_GSS version number in 607 the credential is not supported on the server. In the case, the 608 server returns a rejection status of AUTH_ERROR, with an auth_stat of 609 AUTH_REJECTED_CRED. 611 5.3. RPC Data Exchange 613 The data exchange phase is entered after a context has been 614 successfully set up. The format of the data exchanged depends on the 615 security service used for the request. Although clients can change 616 the security service and QOP used on a per-request basis, this may 617 not be acceptable to all RPC services. For all three modes of 618 service (no data integrity, data integrity, data privacy), the RPC 619 request header has the same format. 621 5.3.1. RPC Request Header 623 The credential has the opaque_auth structure described earlier. The 624 flavor field is set to RPCSEC_GSS. The credential body is created by 625 XDR encoding the rpc_gss_cred_t structure listed earlier into an 626 octet stream, and then opaquely encoding this octet stream as the 627 body field. 629 Values of the fields contained in the rpc_gss_cred_t structure are 630 set as follows. The version field is set to same version value that 631 was used to create the context, which within the scope of this memo 632 will always be RPCSEC_GSS_VERS_1. The gss_proc field is set to 633 RPCSEC_GSS_DATA. The service field is set to indicate the desired 634 service (one of rpc_gss_svc_none, rpc_gss_svc_integrity, or 635 rpc_gss_svc_privacy). The handle field is set to the context handle 636 value received from the RPC server during context creation. The 637 seq_num field can start at any value below MAXSEQ, and must be 638 incremented (by one or more) for successive requests. Use of 639 sequence numbers is described in detail when server processing of the 640 request is discussed. 642 The verifier has the opaque_auth structure described earlier. The 643 flavor field is set to RPCSEC_GSS. The body field is set as follows. 644 The checksum of the RPC header (up to and including the credential) 645 is computed using the gss_sign() call with the desired QOP. This 646 returns the checksum as an opaque octet stream and its length. This 647 is encoded into the body field. Note that the QOP is not explicitly 648 specified anywhere in the request. It is implicit in the checksum or 649 encrypted data. The same QOP value as is used for the header 650 checksum must also be used for the data (for checksumming or 651 encrypting), unless the service used for the request is 652 rpc_gss_svc_none. 654 5.3.2. RPC Request Data 656 5.3.2.1. RPC Request Data - No Data Integrity 658 If the service specified is rpc_gss_svc_none, the data (procedure 659 arguments) are not integrity or privacy protected. They are sent in 660 exactly the same way as they would be if the AUTH_NONE flavor were 661 used (following the verifier). Note, however, that since the RPC 662 header is integrity protected, the sender will still be authenticated 663 in this case. 665 5.3.2.2. RPC Request Data - With Data Integrity 667 When data integrity is used, the request data is represented as 668 follows: 670 struct rpc_gss_integ_data { 671 opaque databody_integ<>; 672 opaque checksum<>; 673 }; 675 The databody_integ field is created as follows. A structure 676 consisting of a sequence number followed by the procedure arguments 677 is constructed. This is shown below as the type rpc_gss_data_t: 679 struct rpc_gss_data_t { 680 unsigned int seq_num; 681 proc_req_arg_t arg; 682 }; 684 Here, seq_num must have the same value as in the credential. The 685 type proc_req_arg_t is the procedure specific XDR type describing the 686 procedure arguments (and so is not specified here). The octet stream 687 corresponding to the XDR encoded rpc_gss_data_t structure and its 688 length are placed in the databody_integ field. Note that because the 689 XDR type of databody_integ is opaque, the XDR encoding of 690 databody_integ will include an initial four octet length field, 691 followed by the XDR encoded octet stream of rpc_gss_data_t. 693 The checksum field represents the checksum of the XDR encoded octet 694 stream corresponding to the XDR encoded rpc_gss_data_t structure 695 (note, this is not the checksum of the databody_integ field). This 696 is obtained using the gss_sign() call, with the same QOP as was used 697 to compute the header checksum (in the verifier). The gss_sign() call 698 returns the checksum as an opaque octet stream and its length. The 699 checksum field of struct rpc_gss_integ_data has an XDR type of 700 opaque. Thus the checksum length from gss_sign() is encoded as a four 701 octet length field, followed by the checksum, padded to a multiple 702 of four octets. 704 5.3.2.3. RPC Request Data - With Data Privacy 706 When data privacy is used, the request data is represented as 707 follows: 709 struct rpc_gss_priv_data { 710 opaque databody_priv<> 711 }; 713 The databody_priv field is created as follows. The rpc_gss_data_t 714 structure described earlier is constructed again in the same way as 715 for the case of data integrity. Next, the gss_seal() call is invoked 716 to encrypt the octet stream corresponding to the rpc_gss_data_t 717 structure, using the same value for QOP as was used for the header 718 checksum (in the verifier). The gss_seal() call returns an opaque 719 octet stream (representing the encrypted rpc_gss_data_t structure) 720 and its length, and this is encoded as the databody_priv field. Since 721 databody_priv has an XDR type of opaque, the length returned by 722 gss_seal() is encoded as the four octet length, followed by the 723 encrypted octet stream (padded to a multiple of four octets). 725 5.3.3. Server Processing of RPC Data Requests 727 5.3.3.1. Context Management 729 When a request is received by the server, the following are verified 730 to be acceptable: 732 * the version number in the credential 734 * the service specified in the credential 736 * the context handle specified in the credential 738 * the header checksum in the verifier 740 * the sequence number (seq_num) specified in the credential (more 741 on this follows) 743 The gss_proc field in the credential must be set to RPCSEC_GSS_DATA 744 for data requests (otherwise, the message will be interpreted as a 745 control message). 747 The server maintains a window of "seq_window" sequence numbers, 748 starting with the last sequence number seen and extending backwards. 749 If a sequence number higher than the last number seen is received, 750 the window is moved forward to the new sequence number. If the last 751 sequence number seen is N, the server is prepared to receive requests 752 with sequence numbers in the range N through (N - seq_window + 1), 753 both inclusive. If the sequence number received falls below this 754 range, it is silently discarded. If the sequence number is within 755 this range, and the server has not seen it, the request is accepted, 756 and the server turns on a bit to "remember" that this sequence number 757 has been seen. If the server determines that it has already seen a 758 sequence number within the window, the request is silently discarded. 759 The server should select a seq_window value based on the number 760 requests it expects to process simultaneously. For example, in a 761 threaded implementation seq_window might be equal to the number of 762 server threads. There are no known security issues with selecting a 763 large window. The primary issue is how much space the server is 764 willing to allocate to keep track of requests received within the 765 window. 767 The reason for discarding requests silently is that the server is 768 unable to determine if the duplicate or out of range request was due 769 to a sequencing problem in the client, network, or the operating 770 system, or due to some quirk in routing, or a replay attack by an 771 intruder. Discarding the request allows the client to recover after 772 timing out, if indeed the duplication was unintentional or well 773 intended. Note that a consequence of the silent discard is that 774 clients may increment the seq_num by more than one. The effect of 775 this is that the window will move forward more quickly. It is not 776 believed that there is any benefit to doing this. 778 Note that the sequence number algorithm requires that the client 779 increment the sequence number even if it is retrying a request with 780 the same RPC transaction identifier. It is not infrequent for 781 clients to get into a situation where they send two or more attempts 782 and a slow server sends the reply for the first attempt. With 783 RPCSEC_GSS, each request and reply will have a unique sequence 784 number. If the client wishes to improve turn around time on the RPC 785 call, it can cache the RPCSEC_GSS sequence number of each request it 786 sends. Then when it receives a response with a matching RPC 787 transaction identifier, it can compute the checksum of each sequence 788 number in the cache to try to match the checksum in the reply's 789 verifier. 791 The data is decoded according to the service specified in the 792 credential. In the case of integrity or privacy, the server ensures 793 that the QOP value is acceptable, and that it is the same as that 794 used for the header checksum in the verifier. Also, in the case of 795 integrity or privacy, the server will reject the message (with a 796 reply status of MSG_ACCEPTED, and an acceptance status of 797 GARBAGE_ARGS) if the sequence number embedded in the request body is 798 different from the sequence number in the credential. 800 5.3.3.2. Server Reply - Request Accepted 802 An MSG_ACCEPTED reply to a request in the data exchange phase will 803 have the verifier's (the verf element in the response) flavor field 804 set to RPCSEC_GSS, and the body field set to the checksum of the 805 sequence number (in network order) of the corresponding request. The 806 QOP used is the same as the QOP used for the corresponding request. 808 If the status of the reply is not SUCCESS, the rest of the message is 809 formatted as usual. 811 If the status of the message is SUCCESS, the format of the rest of 812 the message depends on the service specified in the corresponding 813 request message. Basically, what follows the verifier in this case 814 are the procedure results, formatted in different ways depending on 815 the requested service. 817 If no data integrity was requested, the procedure results are 818 formatted as for the AUTH_NONE security flavor. 820 If data integrity was requested, the results are encoded in exactly 821 the same way as the procedure arguments were in the corresponding 822 request. See the section 'RPC Request Data - With Data Integrity.' 823 The only difference is that the structure representing the 824 procedure's result - proc_res_arg_t - must be substituted in place of 825 the request argument structure proc_req_arg_t. The QOP used for the 826 checksum must be the same as that used for constructing the reply 827 verifier. 829 If data privacy was requested, the results are encoded in exactly the 830 same way as the procedure arguments were in the corresponding 831 request. See the section 'RPC Request Data - With Data Privacy.' 832 The QOP used for encryption must be the same as that used for 833 constructing the reply verifier. 835 5.3.3.3. Server Reply - Request Denied 837 An MSG_DENIED reply (to a data request) is formulated as usual. Two 838 new values (RPCSEC_GSS_NOCRED and RPCSEC_GSS_FAILED) have been 839 defined for the auth_stat type. When the reason for denial of the 840 request is a reject_stat of AUTH_ERROR, one of the two new auth_stat 841 values could be returned in addition to the existing values. These 842 two new values have special significance from the existing reasons 843 for denial of a request. 845 The server maintains a list of contexts for the clients that are 846 currently in session with it. Normally, a context is destroyed when 847 the client ends the session corresponding to it. However, due to 848 resource constraints, the server may destroy a context prematurely 849 (on an LRU basis, or if the server machine is rebooted, for example). 850 In this case, when a client request comes in, there may not be a 851 context corresponding to its handle. The server rejects the request, 852 with the reason RPCSEC_GSS_NOCRED in this case. Upon receiving this 853 error, the client must refresh the context - that is, reestablish it 854 after destroying the old one - and try the request again. This error 855 is also returned if the context handle matches that of a different 856 context that was allocated after the client's context was destroyed 857 (this will be detected by a failure in verifying the header 858 checksum). 860 When the client's sequence number exceeds the maximum the server will 861 allow, the server will reject the request with the reason 862 RPCSEC_GSS_FAILED. Also, if security credentials become stale while 863 in use (due to ticket expiry in the case of the Kerberos V5 864 mechanism, for example), the failures which result cause the 865 RPCSEC_GSS_FAILED reason to be returned. In these cases also, the 866 client must refresh the context, and retry the request. 868 For other errors, retrying will not rectify the problem and the 869 client must not refresh the context until the problem causing the 870 client request to be denied is rectified. 872 If the version field in the credential does not match the version of 873 RPCSEC_GSS that was used when the context was created, the 874 AUTH_BADCRED value is returned. 876 If there is a problem with the credential, such a bad length, illegal 877 control procedure, or an illegal service, the appropriate auth_stat 878 status is AUTH_BADCRED. 880 Other errors can be returned as appropriate. 882 5.4. Context Destruction 884 When the client is done using the session, it must send a control 885 message informing the server that it no longer requires the context. 886 This message is formulated just like a data request packet, with the 887 following differences: the credential has gss_proc set to 888 RPCSEC_GSS_DESTROY, the procedure specified in the header is 889 NULLPROC, and there are no procedure arguments. The sequence number 890 in the request must be valid, and the header checksum in the verifier 891 must be valid, for the server to accept the message. 893 The server sends a response as it would to a data request. The 894 client and server must then destroy the context for the session. 896 If the request to destroy the context fails for some reason, the 897 client need not take any special action. The server must be prepared 898 to deal with situations where clients never inform the server that 899 they no longer are in session and so don't need the server to 900 maintain a context. An LRU mechanism or an aging mechanism should be 901 employed by the server to clean up in such cases. 903 6. Security Considerations 905 6.1. Privacy of Call Header 907 The reader will note that for the privacy option, only the call 908 arguments and results are encrypted. Information about the 909 application in the form of RPC program number, program version 910 number, and program procedure number is transmitted in the clear. 911 Encrypting these fields in the RPC call header would have changed the 912 size and format of the call header. This would have required revising 913 the RPC protocol which was beyond the scope of this proposal. Storing 914 the encrypted numbers in the credential would have obviated a 915 protocol change, but would have introduced more overloading of fields 916 and would have made implementations of RPC more complex. Even if the 917 fields were encrypted somehow, in most cases an attacker can 918 determine the program number and version number by examining the 919 destination address of the request and querying the rpcbind service 920 on the destination host [Srinivasan-bind]. In any case, even by not 921 encrypting the three numbers, RPCSEC_GSS still improves the state of 922 security over what existing RPC services have had available 923 previously. Implementors of new RPC services that are concerned about 924 this risk may opt to design in a "sub-procedure" field that is 925 included in the service specific call arguments. 927 6.2. Sequence number attacks 929 An attacker cannot coax the server into raising the sequence number 930 beyond the range the legitimate client is aware of (and thus engineer 931 a denial of server attack) without constructing an RPC request that 932 will pass the header checksum. If the cost of verifying the header 933 checksum is sufficiently large (depending on the speed of the 934 processor doing the checksum and the cost of checksum algorithm), it 935 is possible to envision a denial of service attack whereby the 936 attacker sends requests that are outside the window. The most trivial 937 one, would be one where the attacker sends a request with a sequence 938 number that is below the window. In this case, even if the header 939 checksum were successfully verified, the server would silently 940 discard it. To guard against this kind of denial of service (stealing 941 processing resources), one might implement a server to examine 942 request's the sequence number to see if it is below the window before 943 verifying the checksum. 945 6.3. Message stealing attacks 947 This proposal does not address attacks where an attacker can block or 948 steal messages without being detected by the server. To implement 949 such protection would be tantamount to assuming a state in the RPC 950 service. RPCSEC_GSS does not worsen this situation. 952 7. Acknowledgements 954 Much of protocol was based on the AUTH_GSSAPI security flavor 955 developed by Open Vision Technologies [Jaspan]. In particular, we 956 acknowledge Barry Jaspan, Marc Horowitz, John Linn, and Ellen 957 McDermott. 959 Raj Srinivasan designed RPCSEC_GSS [Eisler] with input from Mike 960 Eisler. Raj, Roland Schemers, Lin Ling, and Alex Chiu contributed to 961 SunSoft's implementation of RPCSEC_GSS. 963 Barry Jaspan, Marc Horowitz, Hilarie Orman, Martin Rex, and John 964 Wroclawski analyzed the specification and gave valuable feedback. 966 Kathy Slattery proof read the specification. 968 8. References 970 [Eisler] Eisler, M., Schemers, R., and Srinivasan, R. (1996). 971 "Security Mechanism Independence in ONC RPC," To be 972 published in the Proceedings of 1996 Usenix Security 973 Symposium. 975 [Jaspan] Jaspan, B. (1995). "GSS-API Security for ONC RPC," 976 `95 Proceedings of The Internet Society Symposium on 977 Network and Distributed System Security, pp. 144- 978 151. 980 [Linn] Linn, J. (1993). RFC 1508, "Generic Security Service 981 Application Program Interface." 983 [Srinivasan-bind] Srinivasan, R. (1995). RFC 1833, "Binding Protocols 984 for ONC RPC Version 2." 986 [Srinivasan-rpc] Srinivasan, R. (1995). RFC 1831, "RPC: Remote 987 Procedure Call Protocol Specification Version 2." 989 [Srinivasan-xdr] Srinivasan, R. (1995). RFC 1832, "XDR: External Data 990 Representation Standard." 992 9. Authors' Addresses 994 Michael Eisler 995 Sun Microsystems, Inc. 996 M/S UCOS03 997 2550 Garcia Avenue 998 Mountain View, CA 94043 1000 Phone: +1 (719) 599-9026 1002 E-mail: mre@eng.sun.com 1004 Alex Chiu 1005 Sun Microsystems, Inc. 1006 M/S UMPK17-203 1007 2550 Garcia Avenue 1008 Mountain View, CA 94043 1009 Phone: +1 (415) 786-6465 1011 E-mail: hacker@eng.sun.com 1013 Lin Ling 1014 Sun Microsystems, Inc. 1015 M/S UMPK17-201 1016 2550 Garcia Avenue 1017 Mountain View, CA 94043 1019 Phone: +1 (415) 786-5084 1021 E-mail: lling@eng.sun.com