idnits 2.17.1 draft-ietf-oncrpc-rpcsec_gss-04.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-03-28) 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-04', 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. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 515 has weird spacing: '...r octet lengt...' == Line 650 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 (May 1997) is 9814 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) -- Possible downref: Non-RFC (?) normative reference: ref. 'Eisler' -- Possible downref: Non-RFC (?) normative reference: ref. 'Jaspan' ** Obsolete normative reference: RFC 2078 (ref. 'Linn') (Obsoleted by RFC 2743) ** 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: 12 errors (**), 0 flaws (~~), 4 warnings (==), 4 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-ietf-oncrpc-rpcsec_gss-04.txt L. Ling 4 May 1997 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 in November 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 Comments on this document should be sent to the IETF ONCRPC Working 34 Group discussion list: 36 oncrpc-wg@sunroof.eng.sun.com 38 Distribution of this memo is unlimited. 40 Table of Contents 42 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2 43 2. The ONC RPC Message Protocol . . . . . . . . . . . . . . . . . 3 44 3. Flavor Number Assignment . . . . . . . . . . . . . . . . . . . 3 45 4. New auth_stat Values . . . . . . . . . . . . . . . . . . . . . 3 46 5. Elements of the RPCSEC_GSS Security Protocol . . . . . . . . . 4 47 5.1. Version Selection . . . . . . . . . . . . . . . . . . . . . 5 48 5.2. Context Creation . . . . . . . . . . . . . . . . . . . . . . 5 49 5.2.1. Mechanism and QOP Selection . . . . . . . . . . . . . . . 5 50 5.2.2. Context Creation Requests . . . . . . . . . . . . . . . . 6 51 5.2.3. Context Creation Responses . . . . . . . . . . . . . . . . 8 52 5.2.3.1. Context Creation Response - Successful Acceptance . . . 8 53 5.2.3.1.1. Client Processing of Successful Context Creation 54 Responses . . . . . . . . . . . . . . . . . . . . . . 9 55 5.2.3.2. Context Creation Response - Unsuccessful Cases . . . . . 9 56 5.3. RPC Data Exchange . . . . . . . . . . . . . . . . . . . . 10 57 5.3.1. RPC Request Header . . . . . . . . . . . . . . . . . . . 10 58 5.3.2. RPC Request Data . . . . . . . . . . . . . . . . . . . . 10 59 5.3.2.1. RPC Request Data - No Data Integrity . . . . . . . . . 11 60 5.3.2.2. RPC Request Data - With Data Integrity . . . . . . . . 11 61 5.3.2.3. RPC Request Data - With Data Privacy . . . . . . . . . 12 62 5.3.3. Server Processing of RPC Data Requests . . . . . . . . . 12 63 5.3.3.1. Context Management . . . . . . . . . . . . . . . . . . 12 64 5.3.3.2. Server Reply - Request Accepted . . . . . . . . . . . 14 65 5.3.3.3. Server Reply - Request Denied . . . . . . . . . . . . 14 66 5.3.3.4. Mapping of GSS-API Errors to Server Responses . . . . 15 67 5.3.3.4.1. GSS_GetMIC() Failure . . . . . . . . . . . . . . . . 16 68 5.3.3.4.2. GSS_VerifyMIC() Failure . . . . . . . . . . . . . . 16 69 5.3.3.4.3. GSS_Unwrap() Failure . . . . . . . . . . . . . . . . 16 70 5.3.3.4.4. GSS_Wrap() Failure . . . . . . . . . . . . . . . . . 16 71 5.4. Context Destruction . . . . . . . . . . . . . . . . . . . 16 72 6. Set of GSS-API Mechanisms . . . . . . . . . . . . . . . . . 17 73 7. Security Considerations . . . . . . . . . . . . . . . . . . 17 74 7.1. Privacy of Call Header . . . . . . . . . . . . . . . . . . 17 75 7.2. Sequence Number Attacks . . . . . . . . . . . . . . . . . 18 76 7.2.1. Sequence Numbers Above the Window . . . . . . . . . . . 18 77 7.2.2. Sequence Numbers Within or Below the Window . . . . . . 18 78 7.3. Message Stealing Attacks . . . . . . . . . . . . . . . . . 18 79 Appendix A. GSS-API Major Status Codes . . . . . . . . . . . . . 19 80 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 19 81 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 20 83 1. Introduction 85 This document describes the protocol used by the RPCSEC_GSS security 86 flavor. Security flavors have been called authentication flavors for 87 historical reasons. This memo recognizes that there are two other 88 security services besides authentication, integrity, and privacy, and 89 so defines a new RPCSEC_GSS security flavor. 91 The protocol is described using the XDR language [Srinivasan-xdr]. 92 The reader is assumed to be familiar with ONC RPC and the security 93 flavor mechanism [Srinivasan-rpc]. The reader is also assumed to be 94 familiar with the GSS-API framework [Linn]. The RPCSEC_GSS security 95 flavor uses GSS-API interfaces to provide security services that are 96 independent of the underlying security mechanism. 98 2. The ONC RPC Message Protocol 100 This memo refers to the following XDR types of the ONC RPC protocol, 101 which are described in the document entitled Remote Procedure Call 102 Protocol Specification Version 2 [Srinivasan-rpc]: 104 msg_type 105 reply_stat 106 auth_flavor 107 accept_stat 108 reject_stat 109 auth_stat 110 opaque_auth 111 rpc_msg 112 call_body 113 reply_body 114 accepted_reply 115 rejected_reply 117 3. Flavor Number Assignment 119 The RPCSEC_GSS security flavor has been assigned the value of 6: 121 enum auth_flavor { 122 ... 123 RPCSEC_GSS = 6 /* RPCSEC_GSS security flavor */ 124 }; 126 4. New auth_stat Values 128 RPCSEC_GSS requires the addition of two new values to the auth_stat 129 enumerated type definition: 131 enum auth_stat { 132 ... 133 /* 134 * RPCSEC_GSS errors 135 */ 136 RPCSEC_GSS_CREDPROBLEM = 13, 137 RPCSEC_GSS_CTXPROBLEM = 14 138 }; 139 The descriptions of these two new values are defined later in this 140 memo. 142 5. Elements of the RPCSEC_GSS Security Protocol 144 An RPC session based on the RPCSEC_GSS security flavor consists of 145 three phases: context creation, RPC data exchange, and context 146 destruction. In the following discussion, protocol elements for 147 these three phases are described. 149 The following description of the RPCSEC_GSS protocol uses some of the 150 definitions within XDR language description of the RPC protocol. 152 Context creation and destruction use control messages that are not 153 dispatched to service procedures registered by an RPC server. The 154 program and version numbers used in these control messages are the 155 same as the RPC service's program and version numbers. The procedure 156 number used is NULLPROC (zero). A field in the credential 157 information (the gss_proc field which is defined in the 158 rpc_gss_cred_t structure below) specifies whether a message is to be 159 interpreted as a control message or a regular RPC message. If this 160 field is set to RPCSEC_GSS_DATA, no control action is implied; in 161 this case, it is a regular data message. If this field is set to any 162 other value, a control action is implied. This is described in the 163 following sections. 165 Just as with normal RPC data exchange messages, the transaction 166 identifier (the xid field in struct rpc_msg), should be set to unique 167 values on each call for context creation and context destruction. 169 The following definitions are used for describing the protocol. 171 /* RPCSEC_GSS control procedures */ 173 enum rpc_gss_proc_t { 174 RPCSEC_GSS_DATA = 0, 175 RPCSEC_GSS_INIT = 1, 176 RPCSEC_GSS_CONTINUE_INIT = 2, 177 RPCSEC_GSS_DESTROY = 3 178 }; 180 /* RPCSEC_GSS services */ 182 enum rpc_gss_service_t { 183 /* Note: the enumerated value for 0 is reserved. */ 184 rpc_gss_svc_none = 1, 185 rpc_gss_svc_integrity = 2, 186 rpc_gss_svc_privacy = 3 187 }; 188 /* Credential */ 190 /* 191 * Note: version 0 is reserved for possible future 192 * definition of a version negotiation protocol 193 * 194 */ 195 #define RPCSEC_GSS_VERS_1 1 197 struct rpc_gss_cred_t { 198 union switch (unsigned int version) { /* version of 199 RPCSEC_GSS */ 200 case RPCSEC_GSS_VERS_1: 201 struct { 202 rpc_gss_proc_t gss_proc; /* control procedure */ 203 unsigned int seq_num; /* sequence number */ 204 rpc_gss_service_t service; /* service used */ 205 opaque handle<>; /* context handle */ 206 } rpc_gss_cred_vers_1_t; 207 } 208 }; 210 /* Maximum sequence number value */ 212 #define MAXSEQ 0x80000000 214 5.1. Version Selection 216 This document defines just one protocol version (RPCSEC_GSS_VERS_1). 217 The client should assume that the server supports RPCSEC_GSS_VERS_1 218 and issue a Context Creation message (as described in the section 219 'Context Creation'). If the server does not support 220 RPCSEC_GSS_VERS_1, the RPC response will have a reply_stat of 221 MSG_DENIED, a rejection status of AUTH_ERROR, and an auth_stat of 222 AUTH_REJECTED_CRED. 224 5.2. Context Creation 226 Before RPC data is exchanged on a session using the RPCSEC_GSS 227 flavor, a context must be set up between the client and the server. 228 Context creation may involve zero or more RPC exchanges. The number 229 of exchanges depends on the security mechanism. 231 5.2.1. Mechanism and QOP Selection 233 There is no facility in the RPCSEC_GSS protocol to negotiate GSS-API 234 mechanism identifiers or QOP values. At minimum, it is expected that 235 implementations of the RPCSEC_GSS protocol provide interfaces in the 236 RPC programming layer to: 238 * specify mechanism identifiers, QOP values, and RPCSEC_GSS 239 service values on the client side, and to 241 * return mechanism identifiers, QOP values, and RPCSEC_GSS service 242 values on a per-request basis to the server side. 244 Additionally, implementations may depend on negotiation schemes 245 constructed as pseudo-mechanisms under the GSS-API. Because such 246 schemes are below the GSS-API layer, the RPCSEC_GSS protocol, as 247 specified in this document, can make use of them. 249 5.2.2. Context Creation Requests 251 The first RPC request from the client to the server initiates context 252 creation. Within the RPC message protocol's call_body structure, 253 rpcvers is set to 2. prog and vers are always those for the service 254 being accessed. The proc is always set to NULLPROC (zero). 256 Within the RPC message protocol's cred structure, flavor is set to 257 RPCSEC_GSS (6). The opaque data of the cred structure (the body 258 field) constituting the credential encodes the rpc_gss_cred_t 259 structure defined previously. 261 The values of the fields contained in the rpc_gss_cred_t structure 262 are set as follows. The version field is set to the version of the 263 RPCSEC_GSS protocol the client wants to use. The remainder of this 264 memo documents version RPCSEC_GSS_VERS_1 of RPCSEC_GSS, and so the 265 version field would be set to RPCSEC_GSS_VERS_1. The gss_proc field 266 must be set to RPCSEC_GSS_INIT for the first creation request. In 267 subsequent creation requests, the gss_proc field must be set to 268 RPCSEC_GSS_CONTINUE_INIT. In a creation request, the seq_num and 269 service fields are undefined and both must be ignored by the server. 270 In the first creation request, the handle field is NULL (opaque data 271 of zero length). In subsequent creation requests, handle must be 272 equal to the value returned by the server. The handle field serves 273 as the identifier for the context, and will not change for the 274 duration of the context, including responses to 275 RPCSEC_GSS_CONTINUE_INIT. 277 The verifier field in the RPC message header is also described by the 278 opaque_auth structure. All creation requests have the NULL verifier 279 (AUTH_NONE flavor with zero length opaque data). 281 Following the verifier are the call data (procedure specific 282 parameters). Note that the proc field of the call_body structure is 283 set to NULLPROC, and thus normally there would be zero octets 284 following the verifier. However, since there is no RPC data exchange 285 during a context creation, it is safe to transfer information 286 following the verifier. It is necessary to "overload" the call data 287 in this way, rather than pack the GSS-API token into the RPC header, 288 because RPC Version 2 restricts the amount of data that can be sent 289 in the header. The opaque body of the credential and verifier fields 290 can be each at most 400 octets long, and GSS tokens can be longer 291 than 800 octets. 293 The call data for a context creation request is described by the 294 following structure for all creation requests: 296 struct rpc_gss_init_arg { 297 opaque gss_token<>; 298 }; 300 Here, gss_token is the token returned by the call to GSS-API's 301 GSS_Init_sec_context() routine, opaquely encoded. The value of this 302 field will likely be different in each creation request, if there is 303 more than one creation request. If no token is returned by the call 304 to GSS_Init_sec_context(), the context must have been created 305 (assuming no errors), and there will not be any more creation 306 requests. 308 When GSS_Init_sec_context() is called, the parameters 309 replay_det_req_flag and sequence_req_flag must be turned off. The 310 reasons for this are: 312 * ONC RPC can be used over unreliable transports and provides no 313 layer to reliably re-assemble messages. Thus it is possible for 314 gaps in message sequencing to occur, as well as out of order 315 messages. 317 * RPC servers can be multi-threaded, and thus the order in which 318 GSS-API messages are signed or wrapped can be different from the 319 order in which the messages are verified or unwrapped, even if 320 the requests are sent on reliable transports. 322 * To maximize convenience of implementation, the order in which an 323 ONC RPC entity will verify the header and verify/unwrap the body 324 of an RPC call or reply is left unspecified. 326 The RPCSEC_GSS protocol provides for protection from replay attack, 327 yet tolerates out-of-order delivery or processing of messages and 328 tolerates dropped requests. 330 5.2.3. Context Creation Responses 332 5.2.3.1. Context Creation Response - Successful Acceptance 334 The response to a successful creation request has an MSG_ACCEPTED 335 response with a status of SUCCESS. The results field encodes a 336 response with the following structure: 338 struct rpc_gss_init_res { 339 opaque handle<>; 340 unsigned int gss_major; 341 unsigned int gss_minor; 342 unsigned int seq_window; 343 opaque gss_token<>; 344 }; 346 Here, handle is non-NULL opaque data that serves as the context 347 identifier. The client must use this value in all subsequent requests 348 (whether control messages or otherwise). The gss_major and gss_minor 349 fields contain the results of the call to GSS_Accept_sec_context() 350 executed by the server. The values for the gss_major field are 351 defined in Appendix A of this document. The values for the gss_minor 352 field are GSS-API mechanism specific and are defined in the 353 mechanism's specification. If gss_major is not one of GSS_S_COMPLETE 354 or GSS_S_CONTINUE_NEEDED, the context setup has failed; in this case 355 handle and gss_token must be set to NULL by the server. The value of 356 gss_minor is dependent on the value of gss_major and the security 357 mechanism used. The gss_token field contains any token returned by 358 the GSS_Accept_sec_context() call executed by the server. A token 359 may be returned for both successful values of gss_major. If the 360 value is GSS_S_COMPLETE, it indicates that the server is not 361 expecting any more tokens, and the RPC Data Exchange phase must begin 362 on the subsequent request from the client. If the value is 363 GSS_S_CONTINUE_NEEDED, the server is expecting another token. Hence 364 the client must send at least one more creation request (with 365 gss_proc set to RPCSEC_GSS_CONTINUE_INIT in the request's credential) 366 carrying the required token. 368 In a successful response, the seq_window field is set to the sequence 369 window length supported by the server for this context. This window 370 specifies the maximum number of client requests that may be 371 outstanding for this context. The server will accept "seq_window" 372 requests at a time, and these may be out of order. The client may 373 use this number to determine the number of threads that can 374 simultaneously send requests on this context. 376 If gss_major is GSS_S_COMPLETE, the verifier's (the verf element in 377 the response) flavor field is set to RPCSEC_GSS, and the body field 378 set to the checksum of the seq_window (in network order). The QOP 379 used for this checksum is 0 (zero), which is the default QOP. For 380 all other values of gss_major, a NULL verifier (AUTH_NONE flavor with 381 zero-length opaque data) is used. 383 5.2.3.1.1. Client Processing of Successful Context Creation Responses 385 If the value of gss_major in the response is GSS_S_CONTINUE_NEEDED, 386 then the client, per the GSS-API specification, must invoke 387 GSS_Init_sec_context() using the token returned in gss_token in the 388 context creation response. The client must then generate a context 389 creation request, with gss_proc set to RPCSEC_GSS_CONTINUE_INIT. 391 If the value of gss_major in the response is GSS_S_COMPLETE, and if 392 the client's previous invocation of GSS_Init_sec_context() returned a 393 gss_major value of GSS_S_CONTINUE_NEEDED, then the client, per the 394 GSS-API specification, must invoke GSS_Init_sec_context() using the 395 token returned in gss_token in the context creation response. If 396 GSS_Init_sec_context() returns GSS_S_COMPLETE, the context is 397 successfully set up, and the RPC data exchange phase must begin on 398 the subsequent request from the client. 400 5.2.3.2. Context Creation Response - Unsuccessful Cases 402 An MSG_ACCEPTED reply (to a creation request) with an acceptance 403 status of other than SUCCESS has a NULL verifier (flavor set to 404 AUTH_NONE, and zero length opaque data in the body field), and is 405 formulated as usual for different status values. 407 An MSG_DENIED reply (to a creation request) is also formulated as 408 usual. Note that MSG_DENIED could be returned because the server's 409 RPC implementation does not recognize the RPCSEC_GSS security flavor. 410 RFC 1831 does not specify the appropriate reply status in this 411 instance, but common implementation practice appears to be to return 412 a rejection status of AUTH_ERROR with an auth_stat of 413 AUTH_REJECTEDCRED. Even though two new values (RPCSEC_GSS_CREDPROBLEM 414 and RPCSEC_GSS_CTXPROBLEM) have been defined for the auth_stat type, 415 neither of these two can be returned in responses to context creation 416 requests. The auth_stat new values can be used for responses to 417 normal (data) requests. This is described later. 419 MSG_DENIED might also be returned if the RPCSEC_GSS version number in 420 the credential is not supported on the server. In that case, the 421 server returns a rejection status of AUTH_ERROR, with an auth_stat of 422 AUTH_REJECTED_CRED. 424 5.3. RPC Data Exchange 426 The data exchange phase is entered after a context has been 427 successfully set up. The format of the data exchanged depends on the 428 security service used for the request. Although clients can change 429 the security service and QOP used on a per-request basis, this may 430 not be acceptable to all RPC services; some RPC services may "lock" 431 the data exchange phase into using the QOP and service used on the 432 first data exchange message. For all three modes of service (no data 433 integrity, data integrity, data privacy), the RPC request header has 434 the same format. 436 5.3.1. RPC Request Header 438 The credential has the opaque_auth structure described earlier. The 439 flavor field is set to RPCSEC_GSS. The credential body is created by 440 XDR encoding the rpc_gss_cred_t structure listed earlier into an 441 octet stream, and then opaquely encoding this octet stream as the 442 body field. 444 Values of the fields contained in the rpc_gss_cred_t structure are 445 set as follows. The version field is set to same version value that 446 was used to create the context, which within the scope of this memo 447 will always be RPCSEC_GSS_VERS_1. The gss_proc field is set to 448 RPCSEC_GSS_DATA. The service field is set to indicate the desired 449 service (one of rpc_gss_svc_none, rpc_gss_svc_integrity, or 450 rpc_gss_svc_privacy). The handle field is set to the context handle 451 value received from the RPC server during context creation. The 452 seq_num field can start at any value below MAXSEQ, and must be 453 incremented (by one or more) for successive requests. Use of 454 sequence numbers is described in detail when server processing of the 455 request is discussed. 457 The verifier has the opaque_auth structure described earlier. The 458 flavor field is set to RPCSEC_GSS. The body field is set as follows. 459 The checksum of the RPC header (up to and including the credential) 460 is computed using the GSS_GetMIC() call with the desired QOP. This 461 returns the checksum as an opaque octet stream and its length. This 462 is encoded into the body field. Note that the QOP is not explicitly 463 specified anywhere in the request. It is implicit in the checksum or 464 encrypted data. The same QOP value as is used for the header 465 checksum must also be used for the data (for checksumming or 466 encrypting), unless the service used for the request is 467 rpc_gss_svc_none. 469 5.3.2. RPC Request Data 470 5.3.2.1. RPC Request Data - No Data Integrity 472 If the service specified is rpc_gss_svc_none, the data (procedure 473 arguments) are not integrity or privacy protected. They are sent in 474 exactly the same way as they would be if the AUTH_NONE flavor were 475 used (following the verifier). Note, however, that since the RPC 476 header is integrity protected, the sender will still be authenticated 477 in this case. 479 5.3.2.2. RPC Request Data - With Data Integrity 481 When data integrity is used, the request data is represented as 482 follows: 484 struct rpc_gss_integ_data { 485 opaque databody_integ<>; 486 opaque checksum<>; 487 }; 489 The databody_integ field is created as follows. A structure 490 consisting of a sequence number followed by the procedure arguments 491 is constructed. This is shown below as the type rpc_gss_data_t: 493 struct rpc_gss_data_t { 494 unsigned int seq_num; 495 proc_req_arg_t arg; 496 }; 498 Here, seq_num must have the same value as in the credential. The 499 type proc_req_arg_t is the procedure specific XDR type describing the 500 procedure arguments (and so is not specified here). The octet stream 501 corresponding to the XDR encoded rpc_gss_data_t structure and its 502 length are placed in the databody_integ field. Note that because the 503 XDR type of databody_integ is opaque, the XDR encoding of 504 databody_integ will include an initial four octet length field, 505 followed by the XDR encoded octet stream of rpc_gss_data_t. 507 The checksum field represents the checksum of the XDR encoded octet 508 stream corresponding to the XDR encoded rpc_gss_data_t structure 509 (note, this is not the checksum of the databody_integ field). This 510 is obtained using the GSS_GetMIC() call, with the same QOP as was 511 used to compute the header checksum (in the verifier). The 512 GSS_GetMIC() call returns the checksum as an opaque octet stream and 513 its length. The checksum field of struct rpc_gss_integ_data has an 514 XDR type of opaque. Thus the checksum length from GSS_GetMIC() is 515 encoded as a four octet length field, followed by the checksum, 516 padded to a multiple of four octets. 518 5.3.2.3. RPC Request Data - With Data Privacy 520 When data privacy is used, the request data is represented as 521 follows: 523 struct rpc_gss_priv_data { 524 opaque databody_priv<> 525 }; 527 The databody_priv field is created as follows. The rpc_gss_data_t 528 structure described earlier is constructed again in the same way as 529 for the case of data integrity. Next, the GSS_Wrap() call is invoked 530 to encrypt the octet stream corresponding to the rpc_gss_data_t 531 structure, using the same value for QOP (argument qop_req to 532 GSS_Wrap()) as was used for the header checksum (in the verifier) and 533 conf_req_flag (an argument to GSS_Wrap()) of TRUE. The GSS_Wrap() 534 call returns an opaque octet stream (representing the encrypted 535 rpc_gss_data_t structure) and its length, and this is encoded as the 536 databody_priv field. Since databody_priv has an XDR type of opaque, 537 the length returned by GSS_Wrap() is encoded as the four octet 538 length, followed by the encrypted octet stream (padded to a multiple 539 of four octets). 541 5.3.3. Server Processing of RPC Data Requests 543 5.3.3.1. Context Management 545 When a request is received by the server, the following are verified 546 to be acceptable: 548 * the version number in the credential 550 * the service specified in the credential 552 * the context handle specified in the credential 554 * the header checksum in the verifier (via GSS_VerifyMIC()) 556 * the sequence number (seq_num) specified in the credential (more 557 on this follows) 559 The gss_proc field in the credential must be set to RPCSEC_GSS_DATA 560 for data requests (otherwise, the message will be interpreted as a 561 control message). 563 The server maintains a window of "seq_window" sequence numbers, 564 starting with the last sequence number seen and extending backwards. 565 If a sequence number higher than the last number seen is received 566 (AND if GSS_VerifyMIC() on the header checksum from the verifier 567 returns GSS_S_COMPLETE), the window is moved forward to the new 568 sequence number. If the last sequence number seen is N, the server 569 is prepared to receive requests with sequence numbers in the range N 570 through (N - seq_window + 1), both inclusive. If the sequence number 571 received falls below this range, it is silently discarded. If the 572 sequence number is within this range, and the server has not seen it, 573 the request is accepted, and the server turns on a bit to "remember" 574 that this sequence number has been seen. If the server determines 575 that it has already seen a sequence number within the window, the 576 request is silently discarded. The server should select a seq_window 577 value based on the number requests it expects to process 578 simultaneously. For example, in a threaded implementation seq_window 579 might be equal to the number of server threads. There are no known 580 security issues with selecting a large window. The primary issue is 581 how much space the server is willing to allocate to keep track of 582 requests received within the window. 584 The reason for discarding requests silently is that the server is 585 unable to determine if the duplicate or out of range request was due 586 to a sequencing problem in the client, network, or the operating 587 system, or due to some quirk in routing, or a replay attack by an 588 intruder. Discarding the request allows the client to recover after 589 timing out, if indeed the duplication was unintentional or well 590 intended. Note that a consequence of the silent discard is that 591 clients may increment the seq_num by more than one. The effect of 592 this is that the window will move forward more quickly. It is not 593 believed that there is any benefit to doing this. 595 Note that the sequence number algorithm requires that the client 596 increment the sequence number even if it is retrying a request with 597 the same RPC transaction identifier. It is not infrequent for 598 clients to get into a situation where they send two or more attempts 599 and a slow server sends the reply for the first attempt. With 600 RPCSEC_GSS, each request and reply will have a unique sequence 601 number. If the client wishes to improve turn around time on the RPC 602 call, it can cache the RPCSEC_GSS sequence number of each request it 603 sends. Then when it receives a response with a matching RPC 604 transaction identifier, it can compute the checksum of each sequence 605 number in the cache to try to match the checksum in the reply's 606 verifier. 608 The data is decoded according to the service specified in the 609 credential. In the case of integrity or privacy, the server ensures 610 that the QOP value is acceptable, and that it is the same as that 611 used for the header checksum in the verifier. Also, in the case of 612 integrity or privacy, the server will reject the message (with a 613 reply status of MSG_ACCEPTED, and an acceptance status of 614 GARBAGE_ARGS) if the sequence number embedded in the request body is 615 different from the sequence number in the credential. 617 5.3.3.2. Server Reply - Request Accepted 619 An MSG_ACCEPTED reply to a request in the data exchange phase will 620 have the verifier's (the verf element in the response) flavor field 621 set to RPCSEC_GSS, and the body field set to the checksum (the output 622 of GSS_GetMIC()) of the sequence number (in network order) of the 623 corresponding request. The QOP used is the same as the QOP used for 624 the corresponding request. 626 If the status of the reply is not SUCCESS, the rest of the message is 627 formatted as usual. 629 If the status of the message is SUCCESS, the format of the rest of 630 the message depends on the service specified in the corresponding 631 request message. Basically, what follows the verifier in this case 632 are the procedure results, formatted in different ways depending on 633 the requested service. 635 If no data integrity was requested, the procedure results are 636 formatted as for the AUTH_NONE security flavor. 638 If data integrity was requested, the results are encoded in exactly 639 the same way as the procedure arguments were in the corresponding 640 request. See the section 'RPC Request Data - With Data Integrity.' 641 The only difference is that the structure representing the 642 procedure's result - proc_res_arg_t - must be substituted in place of 643 the request argument structure proc_req_arg_t. The QOP used for the 644 checksum must be the same as that used for constructing the reply 645 verifier. 647 If data privacy was requested, the results are encoded in exactly the 648 same way as the procedure arguments were in the corresponding 649 request. See the section 'RPC Request Data - With Data Privacy.' 650 The QOP used for encryption must be the same as that used for 651 constructing the reply verifier. 653 5.3.3.3. Server Reply - Request Denied 655 An MSG_DENIED reply (to a data request) is formulated as usual. Two 656 new values (RPCSEC_GSS_CREDPROBLEM and RPCSEC_GSS_CTXPROBLEM) have 657 been defined for the auth_stat type. When the reason for denial of 658 the request is a reject_stat of AUTH_ERROR, one of the two new 659 auth_stat values could be returned in addition to the existing 660 values. These two new values have special significance from the 661 existing reasons for denial of a request. 663 The server maintains a list of contexts for the clients that are 664 currently in session with it. Normally, a context is destroyed when 665 the client ends the session corresponding to it. However, due to 666 resource constraints, the server may destroy a context prematurely 667 (on an LRU basis, or if the server machine is rebooted, for example). 668 In this case, when a client request comes in, there may not be a 669 context corresponding to its handle. The server rejects the request, 670 with the reason RPCSEC_GSS_CREDPROBLEM in this case. Upon receiving 671 this error, the client must refresh the context - that is, 672 reestablish it after destroying the old one - and try the request 673 again. This error is also returned if the context handle matches 674 that of a different context that was allocated after the client's 675 context was destroyed (this will be detected by a failure in 676 verifying the header checksum). 678 If the GSS_VerifyMIC() call on the header checksum (contained in the 679 verifier) fails to return GSS_S_COMPLETE, the server rejects the 680 request and returns an auth_stat of RPCSEC_GSS_CREDPROBLEM. 682 When the client's sequence number exceeds the maximum the server will 683 allow, the server will reject the request with the reason 684 RPCSEC_GSS_CTXPROBLEM. Also, if security credentials become stale 685 while in use (due to ticket expiry in the case of the Kerberos V5 686 mechanism, for example), the failures which result cause the 687 RPCSEC_GSS_CTXPROBLEM reason to be returned. In these cases also, 688 the client must refresh the context, and retry the request. 690 For other errors, retrying will not rectify the problem and the 691 client must not refresh the context until the problem causing the 692 client request to be denied is rectified. 694 If the version field in the credential does not match the version of 695 RPCSEC_GSS that was used when the context was created, the 696 AUTH_BADCRED value is returned. 698 If there is a problem with the credential, such a bad length, illegal 699 control procedure, or an illegal service, the appropriate auth_stat 700 status is AUTH_BADCRED. 702 Other errors can be returned as appropriate. 704 5.3.3.4. Mapping of GSS-API Errors to Server Responses 706 During the data exchange phase, the server may invoke GSS_GetMIC(), 707 GSS_VerifyMIC(), GSS_Unwrap(), and GSS_Wrap(). If any of these 708 routines fail to return GSS_S_COMPLETE, then various unsuccessful 709 responses can be returned. The are described as follows for each of 710 the aforementioned four interfaces. 712 5.3.3.4.1. GSS_GetMIC() Failure 714 When GSS_GetMIC() is called to generate the verifier in the response, 715 a failure results in an RPC response with a reply status of 716 MSG_DENIED, reject status of AUTH_ERROR and an auth status of 717 RPCSEC_GSS_CTXPROBLEM. 719 When GSS_GetMIC() is called to sign the call results (service is 720 rpc_gss_svc_integrity), a failure results in no RPC response being 721 sent. Since ONC RPC server applications will typically control when a 722 response is sent, the failure indication will be returned to the 723 server application and it can take appropriate action (such as 724 logging the error). 726 5.3.3.4.2. GSS_VerifyMIC() Failure 728 When GSS_VerifyMIC() is called to verify the verifier in request, a 729 failure results in an RPC response with a reply status of MSG_DENIED, 730 reject status of AUTH_ERROR and an auth status of 731 RPCSEC_GSS_CREDPROBLEM. 733 When GSS_VerifyMIC() is called to verify the call arguments (service 734 is rpc_gss_svc_integrity), a failure results in an RPC response with 735 a reply status of MSG_ACCEPTED, and an acceptance status of 736 GARBAGE_ARGS. 738 5.3.3.4.3. GSS_Unwrap() Failure 740 When GSS_Unwrap() is called to decrypt the call arguments (service is 741 rpc_gss_svc_privacy), a failure results in an RPC response with a 742 reply status of MSG_ACCEPTED, and an acceptance status of 743 GARBAGE_ARGS. 745 5.3.3.4.4. GSS_Wrap() Failure 747 When GSS_Wrap() is called to encrypt the call results (service is 748 rpc_gss_svc_privacy), a failure results in no RPC response being 749 sent. Since ONC RPC server applications will typically control when a 750 response is sent, the failure indication will be returned to the 751 application and it can take appropriate action (such as logging the 752 error). 754 5.4. Context Destruction 756 When the client is done using the session, it must send a control 757 message informing the server that it no longer requires the context. 758 This message is formulated just like a data request packet, with the 759 following differences: the credential has gss_proc set to 760 RPCSEC_GSS_DESTROY, the procedure specified in the header is 761 NULLPROC, and there are no procedure arguments. The sequence number 762 in the request must be valid, and the header checksum in the verifier 763 must be valid, for the server to accept the message. 765 The server sends a response as it would to a data request. The 766 client and server must then destroy the context for the session. 768 If the request to destroy the context fails for some reason, the 769 client need not take any special action. The server must be prepared 770 to deal with situations where clients never inform the server that 771 they no longer are in session and so don't need the server to 772 maintain a context. An LRU mechanism or an aging mechanism should be 773 employed by the server to clean up in such cases. 775 6. Set of GSS-API Mechanisms 777 RPCSEC_GSS is effectively a "pass-through" to the GSS-API layer, and 778 as such it is inappropriate for the RPCSEC_GSS specification to 779 enumerate a minimum set of required security mechanisms and/or 780 quality of protections. 782 If an application protocol specification references RPCSEC_GSS, the 783 protocol specification must list a mandatory set of 784 { mechanism, QOP, service } triples, such that an implementation 785 cannot claim conformance to the protocol specification unless it 786 implements the set of triples. Within each triple, mechanism is a 787 GSS-API security mechanism, QOP is a valid quality-of-protection 788 within the mechanism, and service is either rpc_gss_svc_integrity or 789 rpc_gss_svc_privacy. 791 For example, a network filing protocol built on RPC that depends on 792 RPCSEC_GSS for security, might require that Kerberos V5 with the 793 default QOP using the rpc_gss_svc_integrity service be supported by 794 implementations conforming to the network filing protocol 795 specification. 797 7. Security Considerations 799 7.1. Privacy of Call Header 801 The reader will note that for the privacy option, only the call 802 arguments and results are encrypted. Information about the 803 application in the form of RPC program number, program version 804 number, and program procedure number is transmitted in the clear. 805 Encrypting these fields in the RPC call header would have changed the 806 size and format of the call header. This would have required revising 807 the RPC protocol which was beyond the scope of this proposal. Storing 808 the encrypted numbers in the credential would have obviated a 809 protocol change, but would have introduced more overloading of fields 810 and would have made implementations of RPC more complex. Even if the 811 fields were encrypted somehow, in most cases an attacker can 812 determine the program number and version number by examining the 813 destination address of the request and querying the rpcbind service 814 on the destination host [Srinivasan-bind]. In any case, even by not 815 encrypting the three numbers, RPCSEC_GSS still improves the state of 816 security over what existing RPC services have had available 817 previously. Implementors of new RPC services that are concerned about 818 this risk may opt to design in a "sub-procedure" field that is 819 included in the service specific call arguments. 821 7.2. Sequence Number Attacks 823 7.2.1. Sequence Numbers Above the Window 825 An attacker cannot coax the server into raising the sequence number 826 beyond the range the legitimate client is aware of (and thus engineer 827 a denial of server attack) without constructing an RPC request that 828 will pass the header checksum. If the cost of verifying the header 829 checksum is sufficiently large (depending on the speed of the 830 processor doing the checksum and the cost of checksum algorithm), it 831 is possible to envision a denial of service attack (vandalism, in the 832 form of wasting processing resources) whereby the attacker sends 833 requests that are above the window. The simplest method might be for 834 the attacker to monitor the network traffic and then choose a 835 sequence number that is far above the current sequence number. Then 836 the attacker can send bogus requests using the above window sequence 837 number. 839 7.2.2. Sequence Numbers Within or Below the Window 841 If the attacker sends requests that are within or below the window, 842 then even if the header checksum is successfully verified, the server 843 will silently discard the requests because the server assumes it has 844 already processed the request. In this case, a server can optimize by 845 skipping the header checksum verification if the sequence number is 846 below the window, or if it is within the window, not attempt the 847 checksum verification if the sequence number has already been seen. 849 7.3. Message Stealing Attacks 851 This proposal does not address attacks where an attacker can block or 852 steal messages without being detected by the server. To implement 853 such protection would be tantamount to assuming a state in the RPC 854 service. RPCSEC_GSS does not worsen this situation. 856 Appendix A. GSS-API Major Status Codes 858 The GSS-API definition [Linn] does not include numerical values for 859 the various GSS-API major status codes. It is expected that this will 860 be addressed in future RFC. Until then, this appendix defines the 861 values for each GSS-API major status code listed in the GSS-API 862 specification. If in the future, the GSS-API definition defines 863 values for the codes that are different than what follows, then 864 implementors of RPCSEC_GSS will be obliged to map them into the 865 values defined below. 867 Here are the definitions of each GSS_S_* major status that the 868 implementor of RPCSEC_GSS can expect in the gss_major major field of 869 rpc_gss_init_res. See the GSS-API specification for the meaning of 870 each major status. These definitions are not in RPC description 871 language form. The numbers are in base 16 (hexadecimal): 873 GSS_S_COMPLETE 0x00000000 874 GSS_S_CONTINUE_NEEDED 0x00000001 875 GSS_S_DUPLICATE_TOKEN 0x00000002 876 GSS_S_OLD_TOKEN 0x00000004 877 GSS_S_UNSEQ_TOKEN 0x00000008 878 GSS_S_BAD_MECH 0x00010000 879 GSS_S_BAD_NAME 0x00020000 880 GSS_S_BAD_NAMETYPE 0x00030000 881 GSS_S_BAD_BINDINGS 0x00040000 882 GSS_S_BAD_STATUS 0x00050000 883 GSS_S_BAD_SIG 0x00060000 884 GSS_S_NO_CRED 0x00070000 885 GSS_S_NO_CONTEXT 0x00080000 886 GSS_S_DEFECTIVE_TOKEN 0x00090000 887 GSS_S_DEFECTIVE_CREDENTIAL 0x000a0000 888 GSS_S_CREDENTIALS_EXPIRED 0x000b0000 889 GSS_S_CONTEXT_EXPIRED 0x000c0000 890 GSS_S_FAILURE 0x000d0000 891 GSS_S_CALL_INACCESSIBLE_READ 0x01000000 892 GSS_S_CALL_INACCESSIBLE_WRITE 0x02000000 893 GSS_S_CALL_BAD_STRUCTURE 0x03000000 895 Acknowledgements 897 Much of the protocol was based on the AUTH_GSSAPI security flavor 898 developed by Open Vision Technologies [Jaspan]. In particular, we 899 acknowledge Barry Jaspan, Marc Horowitz, John Linn, and Ellen 900 McDermott. 902 Raj Srinivasan designed RPCSEC_GSS [Eisler] with input from Mike 903 Eisler. Raj, Roland Schemers, Lin Ling, and Alex Chiu contributed to 904 Sun Microsystems' implementation of RPCSEC_GSS. 906 Brent Callaghan, Marc Horowitz, Barry Jaspan, John Linn, Hilarie 907 Orman, Martin Rex, Ted Ts'o, and John Wroclawski analyzed the 908 specification and gave valuable feedback. 910 Steve Nahm and Kathy Slattery reviewed various drafts of this 911 specification. 913 References 915 [Eisler] Eisler, M., Schemers, R., and Srinivasan, R. (1996). 916 "Security Mechanism Independence in ONC RPC," 917 Proceedings of the Sixth Annual USENIX Security 918 Symposium, pp. 51-65. 920 [Jaspan] Jaspan, B. (1995). "GSS-API Security for ONC RPC," 921 `95 Proceedings of The Internet Society Symposium on 922 Network and Distributed System Security, pp. 144- 923 151. 925 [Linn] Linn, J. (1997). RFC 2078, "Generic Security Service 926 Application Program Interface, Version 2." 928 [Srinivasan-bind] Srinivasan, R. (1995). RFC 1833, "Binding Protocols 929 for ONC RPC Version 2." 931 [Srinivasan-rpc] Srinivasan, R. (1995). RFC 1831, "RPC: Remote 932 Procedure Call Protocol Specification Version 2." 934 [Srinivasan-xdr] Srinivasan, R. (1995). RFC 1832, "XDR: External Data 935 Representation Standard." 937 Authors' Addresses 939 Michael Eisler 940 Sun Microsystems, Inc. 941 M/S UCOS03 942 2550 Garcia Avenue 943 Mountain View, CA 94043 945 Phone: +1 (719) 599-9026 947 E-mail: mre@eng.sun.com 949 Alex Chiu 950 Sun Microsystems, Inc. 951 M/S UMPK17-203 952 2550 Garcia Avenue 953 Mountain View, CA 94043 955 Phone: +1 (415) 786-6465 957 E-mail: hacker@eng.sun.com 959 Lin Ling 960 Sun Microsystems, Inc. 961 M/S UMPK17-201 962 2550 Garcia Avenue 963 Mountain View, CA 94043 965 Phone: +1 (415) 786-5084 967 E-mail: lling@eng.sun.com