idnits 2.17.1 draft-ietf-oncrpc-rpcsec_gss-03.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-26) 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-03', contains other characters than digits, lowercase letters and dash. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 20 longer pages, the longest (page 2) being 61 lines 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 190 has weird spacing: '...ue_auth cred;...' == Line 191 has weird spacing: '...ue_auth verf;...' == Line 643 has weird spacing: '...r octet lengt...' == Line 778 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 (March 1997) is 9904 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 211 == Outdated reference: A later version (-08) exists of draft-ietf-cat-snego-02 -- 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 (~~), 8 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 ONC RPC Working Group M. Eisler 3 Internet Draft A. Chiu 4 Document: draft-ietf-oncrpc-rpcsec_gss-03.txt L. Ling 5 March 1997 7 RPCSEC_GSS Protocol Specification 9 Abstract 11 This memo describes an ONC/RPC security flavor that allows RPC 12 protocols to access the Generic Security Services Application 13 Programming Interface (referred to henceforth as GSS-API). 15 Status of this Memo 17 This document is an Internet-Draft. Internet-Drafts are working 18 documents of the Internet Engineering Task Force (IETF), its areas, 19 and its working groups. Note that other groups may also distribute 20 working documents as Internet-Drafts. 22 Internet-Drafts are draft documents valid for a maximum of six 23 months. This Internet-Draft expires in September 1997. Internet- 24 Drafts may be updated, replaced, or obsoleted by other documents at 25 any time. It is not appropriate to use Internet-Drafts as reference 26 material or to cite them other than as "work in progress." 28 To learn the current status of any Internet-Draft, please check the 29 "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow 30 Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe), 31 munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or 32 ftp.isi.edu (US West Coast). 34 Comments on this document should be sent to the IETF ONCRPC Working 35 Group discussion list: 37 oncrpc-wg@sunroof.eng.sun.com 39 Distribution of this memo is unlimited. 41 Table of Contents 43 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2 44 2. Review of the RPC Message Protocol . . . . . . . . . . . . . . 2 45 3. Flavor Number Assignment . . . . . . . . . . . . . . . . . . . 5 46 4. New auth_stat Values . . . . . . . . . . . . . . . . . . . . . 5 47 5. Elements of the RPCSEC_GSS Security Protocol . . . . . . . . . 6 48 5.1. Version Selection . . . . . . . . . . . . . . . . . . . . . 7 49 5.2. Context Creation . . . . . . . . . . . . . . . . . . . . . . 7 50 5.2.1. Mechanism and QOP Selection . . . . . . . . . . . . . . . 7 51 5.2.2. Context Creation Requests . . . . . . . . . . . . . . . . 8 52 5.2.3. Context Creation Responses . . . . . . . . . . . . . . . . 9 53 5.2.3.1. Context Creation Response - Successful Acceptance . . . 9 54 5.2.3.1.1. Client Processing of Successful Context Creation 55 Responses . . . . . . . . . . . . . . . . . . . . . 10 56 5.2.3.2. Context Creation Response - Unsuccessful Cases . . . . 10 57 5.3. RPC Data Exchange . . . . . . . . . . . . . . . . . . . . 11 58 5.3.1. RPC Request Header . . . . . . . . . . . . . . . . . . . 11 59 5.3.2. RPC Request Data . . . . . . . . . . . . . . . . . . . . 12 60 5.3.2.1. RPC Request Data - No Data Integrity . . . . . . . . . 12 61 5.3.2.2. RPC Request Data - With Data Integrity . . . . . . . . 12 62 5.3.2.3. RPC Request Data - With Data Privacy . . . . . . . . . 13 63 5.3.3. Server Processing of RPC Data Requests . . . . . . . . . 13 64 5.3.3.1. Context Management . . . . . . . . . . . . . . . . . . 13 65 5.3.3.2. Server Reply - Request Accepted . . . . . . . . . . . 14 66 5.3.3.3. Server Reply - Request Denied . . . . . . . . . . . . 15 67 5.3.3.4. Mapping of GSS-API Errors to Server Responses . . . . 16 68 5.3.3.4.1. GSS_GetMIC() Failure . . . . . . . . . . . . . . . . 16 69 5.3.3.4.2. GSS_VerifyMIC() Failure . . . . . . . . . . . . . . 16 70 5.3.3.4.3. GSS_Unwrap() Failure . . . . . . . . . . . . . . . . 17 71 5.3.3.4.4. GSS_Wrap() Failure . . . . . . . . . . . . . . . . . 17 72 5.4. Context Destruction . . . . . . . . . . . . . . . . . . . 17 73 6. Set of GSS-API Mechanisms . . . . . . . . . . . . . . . . . 17 74 7. Security Considerations . . . . . . . . . . . . . . . . . . 18 75 7.1. Privacy of Call Header . . . . . . . . . . . . . . . . . . 18 76 7.2. Sequence Number Attacks . . . . . . . . . . . . . . . . . 18 77 7.2.1. Sequence Numbers Above the Window . . . . . . . . . . . 18 78 7.2.2. Sequence Numbers Within or Below the Window . . . . . . 18 79 7.3. Message Stealing Attacks . . . . . . . . . . . . . . . . . 19 80 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 19 81 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 19 82 10. Authors' Addresses . . . . . . . . . . . . . . . . . . . . 20 84 1. Introduction 86 This document describes the protocol used by the RPCSEC_GSS security 87 flavor. Security flavors have been called authentication flavors for 88 historical reasons. This memo recognizes that there are two other 89 security services besides authentication, integrity, and privacy, and 90 so defines a new RPCSEC_GSS security flavor. 92 The protocol is described using the XDR language [Srinivasan-xdr]. 93 The reader is assumed to be familiar with ONC RPC and the security 94 flavor mechanism [Srinivasan-rpc]. The reader is also assumed to be 95 familiar with the GSS-API framework [Linn]. The RPCSEC_GSS security 96 flavor uses GSS-API interfaces to provide security services that are 97 independent of the underlying security mechanism. 99 2. Review of the RPC Message Protocol 101 This memo refers to several fields of the RPC protocol. For 102 convenience of reviewers, as this document is in Internet-Draft 103 state, an XDR language description of the RPC message protocol is 104 provided here. 106 /* RPC message type */ 107 enum msg_type { 108 CALL = 0, 109 REPLY = 1 110 }; 112 /* Reply types */ 114 enum reply_stat { 115 MSG_ACCEPTED = 0, 116 MSG_DENIED = 1 117 }; 119 /* Security flavors */ 121 enum auth_flavor { 122 AUTH_NONE = 0, 123 AUTH_SYS = 1, 124 AUTH_SHORT = 2 125 }; 127 /* Status of accepted messages */ 129 enum accept_stat { 130 SUCCESS = 0, 131 PROG_UNAVAIL = 1, 132 PROG_MISMATCH = 2, 133 PROC_UNAVAIL = 3, 134 GARBAGE_ARGS = 4, 135 SYSTEM_ERR = 5 136 }; 138 /* Status of rejected messages */ 140 enum reject_stat { 141 RPC_MISMATCH = 0, 142 AUTH_ERROR = 1 143 }; 145 /* Why authentication failed */ 147 enum auth_stat { 148 AUTH_OK = 0, 150 /* failed at remote end */ 152 AUTH_BADCRED = 1, 153 AUTH_REJECTEDCRED = 2, 154 AUTH_BADVERF = 3, 155 AUTH_REJECTEDVERF = 4, 156 AUTH_TOOWEAK = 5, 158 /* failed locally */ 160 AUTH_INVALIDRESP = 6, 161 AUTH_FAILED = 7 162 }; 164 /* Opaque structure of credential and verifier */ 166 struct opaque_auth { 167 auth_flavor flavor; 168 opaque body<400>; 169 }; 171 /* The RPC message */ 173 struct rpc_msg { 174 unsigned int xid; 175 union switch (msg_type mtype) { 176 case CALL: 177 call_body cbody; 178 case REPLY: 179 reply_body rbody; 180 } body; 181 }; 183 /* Body of RPC call */ 185 struct call_body { 186 unsigned int rpcvers; 187 unsigned int prog; 188 unsigned int vers; 189 unsigned int proc; 190 opaque_auth cred; 191 opaque_auth verf; 193 /* procedure specific parameters start here */ 194 }; 196 /* Body of RPC reply */ 198 union reply_body switch (reply_stat stat) { 199 case MSG_ACCEPTED: 200 accepted_reply areply; 201 case MSG_DENIED: 202 rejected_reply rreply; 203 } reply; 205 /* Accepted reply */ 207 struct accepted_reply { 208 opaque_auth verf; 209 union switch (accept_stat stat) { 210 case SUCCESS: 211 opaque results[0]; 213 /* procedure-specific results start here */ 215 case PROG_MISMATCH: 216 struct { 217 unsigned int low; 218 unsigned int high; 219 } mismatch_info; 221 default: 223 /* 224 * Void. Cases include PROG_UNAVAIL, 225 * PROC_UNAVAIL, GARBAGE_ARGS, and 226 * SYSTEM_ERR. 227 */ 229 void; 230 } reply_data; 231 }; 233 /* Rejected reply */ 235 union rejected_reply switch (reject_stat stat) { 236 case RPC_MISMATCH: 237 struct { 238 unsigned int low; 239 unsigned int high; 240 } mismatch_info; 241 case AUTH_ERROR: 242 auth_stat stat; 243 }; 245 3. Flavor Number Assignment 247 The RPCSEC_GSS security flavor has been assigned the value of 6: 249 enum auth_flavor { 250 ... 251 RPCSEC_GSS = 6 /* RPCSEC_GSS security flavor */ 252 }; 254 4. New auth_stat Values 256 RPCSEC_GSS requires the addition of two new values to the auth_stat 257 enumerated type definition: 259 enum auth_stat { 260 ... 261 /* 262 * RPCSEC_GSS errors 263 */ 264 RPCSEC_GSS_CREDPROBLEM = 13, 265 RPCSEC_GSS_CTXPROBLEM = 14 266 }; 267 The descriptions of these two new values are defined later in this 268 memo. 270 5. Elements of the RPCSEC_GSS Security Protocol 272 An RPC session based on the RPCSEC_GSS security flavor consists of 273 three phases: context creation, RPC data exchange, and context 274 destruction. In the following discussion, protocol elements for 275 these three phases are described. 277 The following description of the RPCSEC_GSS protocol uses some of the 278 definitions within XDR language description of the RPC protocol. 280 Context creation and destruction use control messages that are not 281 dispatched to service procedures registered by an RPC server. The 282 program and version numbers used in these control messages are the 283 same as the RPC service's program and version numbers. The procedure 284 number used is NULLPROC (zero). A field in the credential 285 information (the gss_proc field which is defined in the 286 rpc_gss_cred_t structure below) specifies whether a message is to be 287 interpreted as a control message or a regular RPC message. If this 288 field is set to RPCSEC_GSS_DATA, no control action is implied; in 289 this case, it is a regular data message. If this field is set to any 290 other value, a control action is implied. This is described in the 291 following sections. 293 Just as with normal RPC data exchange messages, the transaction 294 identifier (the xid field in struct rpc_msg), should be set to unique 295 values on each call for context creation and context destruction. 297 The following definitions are used for describing the protocol. 299 /* RPCSEC_GSS control procedures */ 301 enum rpc_gss_proc_t { 302 RPCSEC_GSS_DATA = 0, 303 RPCSEC_GSS_INIT = 1, 304 RPCSEC_GSS_CONTINUE_INIT = 2, 305 RPCSEC_GSS_DESTROY = 3 306 }; 308 /* RPCSEC_GSS services */ 310 enum rpc_gss_service_t { 311 /* Note: the enumerated value for 0 is reserved. */ 312 rpc_gss_svc_none = 1, 313 rpc_gss_svc_integrity = 2, 314 rpc_gss_svc_privacy = 3 315 }; 317 /* Credential */ 319 /* 320 * Note: version 0 is reserved for possible future 321 * definition of a version negotiation protocol 322 * 323 */ 324 #define RPCSEC_GSS_VERS_1 1 326 struct rpc_gss_cred_t { 327 union switch (unsigned int version) { /* version of 328 RPCSEC_GSS */ 329 case RPCSEC_GSS_VERS_1: 330 struct { 331 rpc_gss_proc_t gss_proc; /* control procedure */ 332 unsigned int seq_num; /* sequence number */ 333 rpc_gss_service_t service; /* service used */ 334 opaque handle<>; /* context handle */ 335 } rpc_gss_cred_vers_1_t; 336 } 337 }; 339 /* Maximum sequence number value */ 341 #define MAXSEQ 0x80000000 343 5.1. Version Selection 345 This document defines just one protocol version (RPCSEC_GSS_VERS_1). 346 The client should assume that the server supports RPCSEC_GSS_VERS_1 347 and issue a Context Creation message (as described in the section 348 'Context Creation'). If the server does not support 349 RPCSEC_GSS_VERS_1, the RPC response will have a reply_stat of 350 MSG_DENIED, a rejection status of AUTH_ERROR, and an auth_stat of 351 AUTH_REJECTED_CRED. 353 5.2. Context Creation 355 Before RPC data is exchanged on a session using the RPCSEC_GSS 356 flavor, a context must be set up between the client and the server. 357 Context creation may involve zero or more RPC exchanges. The number 358 of exchanges depends on the security mechanism. 360 5.2.1. Mechanism and QOP Selection 362 There is no facility in the RPCSEC_GSS protocol to negotiate GSS-API 363 mechanism identifiers or QOP values. At minimum, it is expected that 364 implementations of the RPCSEC_GSS protocol provide interfaces in the 365 RPC programming layer to: 367 * specify mechanism identifiers, QOP values, and RPCSEC_GSS 368 service values on the client side, and to 370 * return mechanism identifiers, QOP values, and RPCSEC_GSS service 371 values on a per-request basis to the server side. 373 Additionally, implementations may depend on negotiation schemes 374 constructed as pseudo-mechanisms under the GSS-API, such as the 375 Simple GSS-API Negotiation Mechanism [Baize]. Because such schemes 376 are below the GSS-API layer, the RPCSEC_GSS protocol, as specified in 377 this document, can make use of them. 379 5.2.2. Context Creation Requests 381 The first RPC request from the client to the server initiates context 382 creation. Within the RPC message protocol's call_body structure, 383 rpcvers is set to 2. prog and vers are always those for the service 384 being accessed. The proc is always set to NULLPROC (zero). 386 Within the RPC message protocol's cred structure, flavor is set to 387 RPCSEC_GSS (6). The opaque data of the cred structure (the body 388 field) constituting the credential encodes the rpc_gss_cred_t 389 structure defined previously. 391 The values of the fields contained in the rpc_gss_cred_t structure 392 are set as follows. The version field is set to the version of the 393 RPCSEC_GSS protocol the client wants to use. The remainder of this 394 memo documents version RPCSEC_GSS_VERS_1 of RPCSEC_GSS, and so the 395 version field would be set to RPCSEC_GSS_VERS_1. The gss_proc field 396 must be set to RPCSEC_GSS_INIT for the first creation request. In 397 subsequent creation requests, the gss_proc field must be set to 398 RPCSEC_GSS_CONTINUE_INIT. In a creation request, the seq_num and 399 service fields are undefined and both must be ignored by the server. 400 In the first creation request, the handle field is NULL (opaque data 401 of zero length). In subsequent creation requests, handle must be 402 equal to the value returned by the server. The handle field serves 403 as the identifier for the context, and will not change for the 404 duration of the context, including responses to 405 RPCSEC_GSS_CONTINUE_INIT. 407 The verifier field in the RPC message header is also described by the 408 opaque_auth structure. All creation requests have the NULL verifier 409 (AUTH_NONE flavor with zero length opaque data). 411 Following the verifier are the call data (procedure specific 412 parameters). Note that the proc field of the call_body structure is 413 set to NULLPROC, and thus normally there would be zero octets 414 following the verifier. However, since there is no RPC data exchange 415 during a context creation, it is safe to transfer information 416 following the verifier. It is necessary to "overload" the call data 417 in this way, rather than pack the GSS-API token into the RPC header, 418 because RPC Version 2 restricts the amount of data that can be sent 419 in the header. The opaque body of the credential and verifier fields 420 can be each at most 400 octets long, and GSS tokens can be longer 421 than 800 octets. 423 The call data for a context creation request is described by the 424 following structure for all creation requests: 426 struct rpc_gss_init_arg { 427 opaque gss_token<>; 428 }; 430 Here, gss_token is the token returned by the call to GSS-API's 431 GSS_Init_sec_context() routine, opaquely encoded. The value of this 432 field will likely be different in each creation request, if there is 433 more than one creation request. If no token is returned by the call 434 to GSS_Init_sec_context(), the context must have been created 435 (assuming no errors), and there will not be any more creation 436 requests. 438 When GSS_Init_sec_context() is called, the parameters 439 replay_det_req_flag and sequence_req_flag must be turned off. The 440 reasons for this are: 442 * ONC RPC can be used over unreliable transports and provides no 443 layer to reliably re-assemble messages. Thus it is possible for 444 gaps in message sequencing to occur, as well as out of order 445 messages. 447 * RPC servers can be multi-threaded, and thus the order in which 448 GSS-API messages are signed or wrapped can be different from the 449 order in which the messages are verified or unwrapped, even if 450 the requests are sent on reliable transports. 452 * To maximize convenience of implementation, the order in which an 453 ONC RPC entity will verify the header and verify/unwrap the body 454 of an RPC call or reply is left unspecified. 456 The RPCSEC_GSS protocol provides for protection from replay attack, 457 yet tolerates out-of-order delivery or processing of messages and 458 tolerates dropped requests. 460 5.2.3. Context Creation Responses 462 5.2.3.1. Context Creation Response - Successful Acceptance 464 The response to a successful creation request has an MSG_ACCEPTED 465 response with a status of SUCCESS. The results field encodes result 466 argument that has the following structure: 468 struct rpc_gss_init_res { 469 opaque handle<>; 470 unsigned int gss_major; 471 unsigned int gss_minor; 472 unsigned int seq_window; 473 opaque gss_token<>; 474 }; 476 Here, handle is non-NULL opaque data that serves as the context 477 identifier. The client must use this value in all subsequent requests 478 (whether control messages or otherwise). The gss_major and gss_minor 479 fields contain the results of the call to GSS_Accept_sec_context() 480 executed by the server. If gss_major is not one of GSS_S_COMPLETE or 481 GSS_S_CONTINUE_NEEDED, the context setup has failed; in this case 482 handle and gss_token must be set to NULL by the server. The value of 483 gss_minor is dependent on the value of gss_major and the security 484 mechanism used. The gss_token field contains any token returned by 485 the GSS_Accept_sec_context() call executed by the server. A token 486 may be returned for both successful values of gss_major. If the 487 value is GSS_S_COMPLETE, it indicates that the server is not 488 expecting any more tokens, and the RPC Data Exchange phase must begin 489 on the subsequent request from the client. If the value is 490 GSS_S_CONTINUE_NEEDED, the server is expecting another token. Hence 491 the client must send at least one more creation request (with 492 gss_proc set to RPCSEC_GSS_CONTINUE_INIT in the request's credential) 493 carrying the required token. 495 In a successful response, the seq_window field is set to the sequence 496 window length supported by the server for this context. This window 497 specifies the maximum number of client requests that may be 498 outstanding for this context. The server will accept "seq_window" 499 requests at a time, and these may be out of order. The client may 500 use this number to determine the number of threads that can 501 simultaneously send requests on this context. 503 If gss_major is GSS_S_COMPLETE, the verifier's (the verf element in 504 the response) flavor field to to RPCSEC_GSS, and the body field set 505 to the checksum of the seq_window (in network order). The QOP used 506 for this checksum is 0 (zero), which is the default QOP. For all 507 other values of gss_major, a NULL verifier (AUTH_NONE flavor with 508 zero-length opaque data) is used. 510 5.2.3.1.1. Client Processing of Successful Context Creation Responses 512 If the value of gss_major in the response is GSS_S_CONTINUE_NEEDED, 513 then the client, per the GSS-API specification, must invoke 514 GSS_Init_sec_context() using the token returned in gss_token in the 515 context creation response. The client must then generate a context 516 creation request, with gss_proc set to RPCSEC_GSS_CONTINUE_INIT. 518 If the value of gss_major in the response is GSS_S_COMPLETE, and if 519 the client's previous invocation of GSS_Init_sec_context() returned a 520 gss_major value of GSS_S_CONTINUE_NEEDED, then the client, per the 521 GSS-API specification, must invoke GSS_Init_sec_context() using the 522 token returned in gss_token in the context creation response. If 523 GSS_Init_sec_context() returns GSS_S_COMPLETE, the context is 524 successfully set up, and the RPC data exchange phase must begin on 525 the subsequent request from the client. 527 5.2.3.2. Context Creation Response - Unsuccessful Cases 529 An MSG_ACCEPTED reply (to a creation request) with an acceptance 530 status of other than SUCCESS has a NULL verifier (flavor set to 531 AUTH_NONE, and zero length opaque data in the body field), and is 532 formulated as usual for different status values. 534 An MSG_DENIED reply (to a creation request) is also formulated as 535 usual. Note that MSG_DENIED could be returned because the server's 536 RPC implementation does not recognize the RPCSEC_GSS security flavor. 537 RFC 1831 does not specify the appropriate reply status in this 538 instance. Solaris 2 implementations return a rejection status of 539 AUTH_ERROR with an auth_stat of AUTH_REJECTEDCRED. Even though two 540 new values (RPCSEC_GSS_CREDPROBLEM and RPCSEC_GSS_CTXPROBLEM) have 541 been defined for the auth_stat type, neither of these two can be 542 returned in responses to context creation requests. The new values 543 are relevant to for responses to normal (data) requests. This is 544 described later. 546 MSG_DENIED might also be returned if the RPCSEC_GSS version number in 547 the credential is not supported on the server. In that case, the 548 server returns a rejection status of AUTH_ERROR, with an auth_stat of 549 AUTH_REJECTED_CRED. 551 5.3. RPC Data Exchange 553 The data exchange phase is entered after a context has been 554 successfully set up. The format of the data exchanged depends on the 555 security service used for the request. Although clients can change 556 the security service and QOP used on a per-request basis, this may 557 not be acceptable to all RPC services; some RPC services may "lock" 558 the data exchange phase into using the the QOP and service used on 559 the first data exchange message. For all three modes of service (no 560 data integrity, data integrity, data privacy), the RPC request header 561 has the same format. 563 5.3.1. RPC Request Header 565 The credential has the opaque_auth structure described earlier. The 566 flavor field is set to RPCSEC_GSS. The credential body is created by 567 XDR encoding the rpc_gss_cred_t structure listed earlier into an 568 octet stream, and then opaquely encoding this octet stream as the 569 body field. 571 Values of the fields contained in the rpc_gss_cred_t structure are 572 set as follows. The version field is set to same version value that 573 was used to create the context, which within the scope of this memo 574 will always be RPCSEC_GSS_VERS_1. The gss_proc field is set to 575 RPCSEC_GSS_DATA. The service field is set to indicate the desired 576 service (one of rpc_gss_svc_none, rpc_gss_svc_integrity, or 577 rpc_gss_svc_privacy). The handle field is set to the context handle 578 value received from the RPC server during context creation. The 579 seq_num field can start at any value below MAXSEQ, and must be 580 incremented (by one or more) for successive requests. Use of 581 sequence numbers is described in detail when server processing of the 582 request is discussed. 584 The verifier has the opaque_auth structure described earlier. The 585 flavor field is set to RPCSEC_GSS. The body field is set as follows. 586 The checksum of the RPC header (up to and including the credential) 587 is computed using the GSS_GetMIC() call with the desired QOP. This 588 returns the checksum as an opaque octet stream and its length. This 589 is encoded into the body field. Note that the QOP is not explicitly 590 specified anywhere in the request. It is implicit in the checksum or 591 encrypted data. The same QOP value as is used for the header 592 checksum must also be used for the data (for checksumming or 593 encrypting), unless the service used for the request is 594 rpc_gss_svc_none. 596 5.3.2. RPC Request Data 598 5.3.2.1. RPC Request Data - No Data Integrity 600 If the service specified is rpc_gss_svc_none, the data (procedure 601 arguments) are not integrity or privacy protected. They are sent in 602 exactly the same way as they would be if the AUTH_NONE flavor were 603 used (following the verifier). Note, however, that since the RPC 604 header is integrity protected, the sender will still be authenticated 605 in this case. 607 5.3.2.2. RPC Request Data - With Data Integrity 609 When data integrity is used, the request data is represented as 610 follows: 612 struct rpc_gss_integ_data { 613 opaque databody_integ<>; 614 opaque checksum<>; 615 }; 617 The databody_integ field is created as follows. A structure 618 consisting of a sequence number followed by the procedure arguments 619 is constructed. This is shown below as the type rpc_gss_data_t: 621 struct rpc_gss_data_t { 622 unsigned int seq_num; 623 proc_req_arg_t arg; 624 }; 626 Here, seq_num must have the same value as in the credential. The 627 type proc_req_arg_t is the procedure specific XDR type describing the 628 procedure arguments (and so is not specified here). The octet stream 629 corresponding to the XDR encoded rpc_gss_data_t structure and its 630 length are placed in the databody_integ field. Note that because the 631 XDR type of databody_integ is opaque, the XDR encoding of 632 databody_integ will include an initial four octet length field, 633 followed by the XDR encoded octet stream of rpc_gss_data_t. 635 The checksum field represents the checksum of the XDR encoded octet 636 stream corresponding to the XDR encoded rpc_gss_data_t structure 637 (note, this is not the checksum of the databody_integ field). This 638 is obtained using the GSS_GetMIC() call, with the same QOP as was 639 used to compute the header checksum (in the verifier). The 640 GSS_GetMIC() call returns the checksum as an opaque octet stream and 641 its length. The checksum field of struct rpc_gss_integ_data has an 642 XDR type of opaque. Thus the checksum length from GSS_GetMIC() is 643 encoded as a four octet length field, followed by the checksum, 644 padded to a multiple of four octets. 646 5.3.2.3. RPC Request Data - With Data Privacy 648 When data privacy is used, the request data is represented as 649 follows: 651 struct rpc_gss_priv_data { 652 opaque databody_priv<> 653 }; 655 The databody_priv field is created as follows. The rpc_gss_data_t 656 structure described earlier is constructed again in the same way as 657 for the case of data integrity. Next, the GSS_Wrap() call is invoked 658 to encrypt the octet stream corresponding to the rpc_gss_data_t 659 structure, using the same value for QOP (argument qop_req to 660 GSS_Wrap()) as was used for the header checksum (in the verifier) and 661 conf_req_flag (an argument to GSS_Wrap()) of TRUE. The GSS_Wrap() 662 call returns an opaque octet stream (representing the encrypted 663 rpc_gss_data_t structure) and its length, and this is encoded as the 664 databody_priv field. Since databody_priv has an XDR type of opaque, 665 the length returned by GSS_Wrap() is encoded as the four octet 666 length, followed by the encrypted octet stream (padded to a multiple 667 of four octets). 669 5.3.3. Server Processing of RPC Data Requests 671 5.3.3.1. Context Management 673 When a request is received by the server, the following are verified 674 to be acceptable: 676 * the version number in the credential 678 * the service specified in the credential 680 * the context handle specified in the credential 682 * the header checksum in the verifier (via GSS_VerifyMIC()) 684 * the sequence number (seq_num) specified in the credential (more 685 on this follows) 687 The gss_proc field in the credential must be set to RPCSEC_GSS_DATA 688 for data requests (otherwise, the message will be interpreted as a 689 control message). 691 The server maintains a window of "seq_window" sequence numbers, 692 starting with the last sequence number seen and extending backwards. 693 If a sequence number higher than the last number seen is received 694 (AND if GSS_VerifyMIC() on the header checksum from the verifier 695 returns GSS_S_COMPLETE), the window is moved forward to the new 696 sequence number. If the last sequence number seen is N, the server 697 is prepared to receive requests with sequence numbers in the range N 698 through (N - seq_window + 1), both inclusive. If the sequence number 699 received falls below this range, it is silently discarded. If the 700 sequence number is within this range, and the server has not seen it, 701 the request is accepted, and the server turns on a bit to "remember" 702 that this sequence number has been seen. If the server determines 703 that it has already seen a sequence number within the window, the 704 request is silently discarded. The server should select a seq_window 705 value based on the number requests it expects to process 706 simultaneously. For example, in a threaded implementation seq_window 707 might be equal to the number of server threads. There are no known 708 security issues with selecting a large window. The primary issue is 709 how much space the server is willing to allocate to keep track of 710 requests received within the window. 712 The reason for discarding requests silently is that the server is 713 unable to determine if the duplicate or out of range request was due 714 to a sequencing problem in the client, network, or the operating 715 system, or due to some quirk in routing, or a replay attack by an 716 intruder. Discarding the request allows the client to recover after 717 timing out, if indeed the duplication was unintentional or well 718 intended. Note that a consequence of the silent discard is that 719 clients may increment the seq_num by more than one. The effect of 720 this is that the window will move forward more quickly. It is not 721 believed that there is any benefit to doing this. 723 Note that the sequence number algorithm requires that the client 724 increment the sequence number even if it is retrying a request with 725 the same RPC transaction identifier. It is not infrequent for 726 clients to get into a situation where they send two or more attempts 727 and a slow server sends the reply for the first attempt. With 728 RPCSEC_GSS, each request and reply will have a unique sequence 729 number. If the client wishes to improve turn around time on the RPC 730 call, it can cache the RPCSEC_GSS sequence number of each request it 731 sends. Then when it receives a response with a matching RPC 732 transaction identifier, it can compute the checksum of each sequence 733 number in the cache to try to match the checksum in the reply's 734 verifier. 736 The data is decoded according to the service specified in the 737 credential. In the case of integrity or privacy, the server ensures 738 that the QOP value is acceptable, and that it is the same as that 739 used for the header checksum in the verifier. Also, in the case of 740 integrity or privacy, the server will reject the message (with a 741 reply status of MSG_ACCEPTED, and an acceptance status of 742 GARBAGE_ARGS) if the sequence number embedded in the request body is 743 different from the sequence number in the credential. 745 5.3.3.2. Server Reply - Request Accepted 747 An MSG_ACCEPTED reply to a request in the data exchange phase will 748 have the verifier's (the verf element in the response) flavor field 749 set to RPCSEC_GSS, and the body field set to the checksum (the output 750 of GSS_GetMIC()) of the sequence number (in network order) of the 751 corresponding request. The QOP used is the same as the QOP used for 752 the corresponding request. 754 If the status of the reply is not SUCCESS, the rest of the message is 755 formatted as usual. 757 If the status of the message is SUCCESS, the format of the rest of 758 the message depends on the service specified in the corresponding 759 request message. Basically, what follows the verifier in this case 760 are the procedure results, formatted in different ways depending on 761 the requested service. 763 If no data integrity was requested, the procedure results are 764 formatted as for the AUTH_NONE security flavor. 766 If data integrity was requested, the results are encoded in exactly 767 the same way as the procedure arguments were in the corresponding 768 request. See the section 'RPC Request Data - With Data Integrity.' 769 The only difference is that the structure representing the 770 procedure's result - proc_res_arg_t - must be substituted in place of 771 the request argument structure proc_req_arg_t. The QOP used for the 772 checksum must be the same as that used for constructing the reply 773 verifier. 775 If data privacy was requested, the results are encoded in exactly the 776 same way as the procedure arguments were in the corresponding 777 request. See the section 'RPC Request Data - With Data Privacy.' 778 The QOP used for encryption must be the same as that used for 779 constructing the reply verifier. 781 5.3.3.3. Server Reply - Request Denied 783 An MSG_DENIED reply (to a data request) is formulated as usual. Two 784 new values (RPCSEC_GSS_CREDPROBLEM and RPCSEC_GSS_CTXPROBLEM) have 785 been defined for the auth_stat type. When the reason for denial of 786 the request is a reject_stat of AUTH_ERROR, one of the two new 787 auth_stat values could be returned in addition to the existing 788 values. These two new values have special significance from the 789 existing reasons for denial of a request. 791 The server maintains a list of contexts for the clients that are 792 currently in session with it. Normally, a context is destroyed when 793 the client ends the session corresponding to it. However, due to 794 resource constraints, the server may destroy a context prematurely 795 (on an LRU basis, or if the server machine is rebooted, for example). 796 In this case, when a client request comes in, there may not be a 797 context corresponding to its handle. The server rejects the request, 798 with the reason RPCSEC_GSS_CREDPROBLEM in this case. Upon receiving 799 this error, the client must refresh the context - that is, 800 reestablish it after destroying the old one - and try the request 801 again. This error is also returned if the context handle matches 802 that of a different context that was allocated after the client's 803 context was destroyed (this will be detected by a failure in 804 verifying the header checksum). 806 If the GSS_VerifyMIC() call in the verifier (the header checksum) 807 fails to return GSS_S_COMPLETE, the server rejects the requests and 808 returns an auth_stat of RPCSEC_GSS_CREDPROBLEM. 810 When the client's sequence number exceeds the maximum the server will 811 allow, the server will reject the request with the reason 812 RPCSEC_GSS_CTXPROBLEM. Also, if security credentials become stale 813 while in use (due to ticket expiry in the case of the Kerberos V5 814 mechanism, for example), the failures which result cause the 815 RPCSEC_GSS_CTXPROBLEM reason to be returned. In these cases also, 816 the client must refresh the context, and retry the request. 818 For other errors, retrying will not rectify the problem and the 819 client must not refresh the context until the problem causing the 820 client request to be denied is rectified. 822 If the version field in the credential does not match the version of 823 RPCSEC_GSS that was used when the context was created, the 824 AUTH_BADCRED value is returned. 826 If there is a problem with the credential, such a bad length, illegal 827 control procedure, or an illegal service, the appropriate auth_stat 828 status is AUTH_BADCRED. 830 Other errors can be returned as appropriate. 832 5.3.3.4. Mapping of GSS-API Errors to Server Responses 834 During the data exchange phase, the server may invoke GSS_GetMIC(), 835 GSS_VerifyMIC(), GSS_Unwrap(), and GSS_Wrap(). If any of these 836 routines fail to return GSS_S_COMPLETE, then various unsuccessful 837 responses can be returned. The are described as follows for each of 838 the aforementioned four interfaces. 840 5.3.3.4.1. GSS_GetMIC() Failure 842 When GSS_GetMIC() is called to generate the verifier in the response, 843 a failure results in an RPC response with a reply status of 844 MSG_DENIED, reject status of AUTH_ERROR and an auth status of 845 RPCSEC_GSS_CTXPROBLEM. 847 When GSS_GetMIC() is called to sign the call results (service is 848 rpc_gss_svc_integrity), a failure results in no RPC response being 849 sent. Since ONC RPC server applications will typically control when a 850 response is sent, the failure indication will be returned to the 851 server application and it can take appropriate action (such as 852 logging the error). 854 5.3.3.4.2. GSS_VerifyMIC() Failure 856 When GSS_VerifyMIC() is called to verify the verifier in request, a 857 failure results in an RPC response with a reply status of MSG_DENIED, 858 reject status of AUTH_ERROR and an auth status of 859 RPCSEC_GSS_CREDPROBLEM. 861 When GSS_VerifyMIC() is called to verify the call arguments (service 862 is rpc_gss_svc_integrity), a failure results in an RPC response with 863 a reply status of MSG_ACCEPTED, and an acceptance status of 864 GARBAGE_ARGS. 866 5.3.3.4.3. GSS_Unwrap() Failure 868 When GSS_Unwrap() is called to decrypt the call arguments (service is 869 rpc_gss_svc_privacy), a failure results in an RPC response with a 870 reply status of MSG_ACCEPTED, and an acceptance status of 871 GARBAGE_ARGS. 873 5.3.3.4.4. GSS_Wrap() Failure 875 When GSS_Wrap() is called to encrypt the call results (service is 876 rpc_gss_svc_privacy), a failure results in no RPC response being 877 sent. Since ONC RPC server applications will typically control when a 878 response is sent, the failure indication will be returned to the 879 application and it can take appropriate action (such as logging the 880 error). 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. Set of GSS-API Mechanisms 905 RPCSEC_GSS is effectively a "pass-through" to the GSS-API layer, and 906 as such it is inappropriate for the RPCSEC_GSS specification to 907 enumerate a minimum set of required security mechanisms and/or 908 quality of protections. 910 If an application protocol specification references RPCSEC_GSS, the 911 protocol specification must list a mandatory set of 912 { mechanism, QOP, service } triples, such that an implementation 913 cannot claim conformance to the protocol specification unless it 914 implements the set of triples. Within each triple, mechanism is a 915 GSS-API security mechanism, QOP is a valid quality-of-protection 916 within the mechanism, and service is either rpc_gss_svc_integrity or 917 rpc_gss_svc_privacy. 919 For example, a network filing protocol built on RPC that depends on 920 RPCSEC_GSS for security, might require that Kerberos V5 with the 921 default QOP using the rpc_gss_svc_integrity service be supported by 922 implementations conforming to the network filing protocol 923 specification. 925 7. Security Considerations 927 7.1. Privacy of Call Header 929 The reader will note that for the privacy option, only the call 930 arguments and results are encrypted. Information about the 931 application in the form of RPC program number, program version 932 number, and program procedure number is transmitted in the clear. 933 Encrypting these fields in the RPC call header would have changed the 934 size and format of the call header. This would have required revising 935 the RPC protocol which was beyond the scope of this proposal. Storing 936 the encrypted numbers in the credential would have obviated a 937 protocol change, but would have introduced more overloading of fields 938 and would have made implementations of RPC more complex. Even if the 939 fields were encrypted somehow, in most cases an attacker can 940 determine the program number and version number by examining the 941 destination address of the request and querying the rpcbind service 942 on the destination host [Srinivasan-bind]. In any case, even by not 943 encrypting the three numbers, RPCSEC_GSS still improves the state of 944 security over what existing RPC services have had available 945 previously. Implementors of new RPC services that are concerned about 946 this risk may opt to design in a "sub-procedure" field that is 947 included in the service specific call arguments. 949 7.2. Sequence Number Attacks 951 7.2.1. Sequence Numbers Above the Window 953 An attacker cannot coax the server into raising the sequence number 954 beyond the range the legitimate client is aware of (and thus engineer 955 a denial of server attack) without constructing an RPC request that 956 will pass the header checksum. If the cost of verifying the header 957 checksum is sufficiently large (depending on the speed of the 958 processor doing the checksum and the cost of checksum algorithm), it 959 is possible to envision a denial of service attack (vandalism, in the 960 form of wasting processing resources) whereby the attacker sends 961 requests that are above the window. The simplest method might be for 962 the attacker to monitor the network traffic and then choose a 963 sequence number that is far above the current sequence number. Then 964 the attacker can send bogus requests using the above window sequence 965 number. 967 7.2.2. Sequence Numbers Within or Below the Window 969 If the attacker sends requests that within or below the window, then 970 even if the header checksum is successfully verified, the server will 971 silently discard the requests because the server assumes it has 972 already processed the request. In this case, a server can optimize by 973 skipping the header checksum verification if the sequence number is 974 below the window, or if it is within the window, do not attempt the 975 checksum verification if the sequence number has already been seen. 977 7.3. Message Stealing Attacks 979 This proposal does not address attacks where an attacker can block or 980 steal messages without being detected by the server. To implement 981 such protection would be tantamount to assuming a state in the RPC 982 service. RPCSEC_GSS does not worsen this situation. 984 8. Acknowledgements 986 Much of protocol was based on the AUTH_GSSAPI security flavor 987 developed by Open Vision Technologies [Jaspan]. In particular, we 988 acknowledge Barry Jaspan, Marc Horowitz, John Linn, and Ellen 989 McDermott. 991 Raj Srinivasan designed RPCSEC_GSS [Eisler] with input from Mike 992 Eisler. Raj, Roland Schemers, Lin Ling, and Alex Chiu contributed to 993 SunSoft's implementation of RPCSEC_GSS. 995 Brent Callaghan, Marc Horowitz, Barry Jaspan, John Linn, Hilarie 996 Orman, Martin Rex, Ted Ts'o, and John Wroclawski analyzed the 997 specification and gave valuable feedback. 999 Steve Nahm and Kathy Slattery reviewed various drafts of this 1000 specification. 1002 9. References 1004 [Baize] Baize, E., and Pinkas, D. (1996). 1005 draft-ietf-cat-snego-02.txt "Simple GSS-API 1006 Negotiation Mechanism," This is a work in progress 1007 which may be updated, replaced, or obsoleted at any 1008 time. 1010 [Eisler] Eisler, M., Schemers, R., and Srinivasan, R. (1996). 1011 "Security Mechanism Independence in ONC RPC," To be 1012 published in the Proceedings of 1996 Usenix Security 1013 Symposium. 1015 [Jaspan] Jaspan, B. (1995). "GSS-API Security for ONC RPC," 1016 `95 Proceedings of The Internet Society Symposium on 1017 Network and Distributed System Security, pp. 144- 1018 151. 1020 [Linn] Linn, J. (1997). RFC 2078, "Generic Security Service 1021 Application Program Interface, Version 2." 1023 [Srinivasan-bind] Srinivasan, R. (1995). RFC 1833, "Binding Protocols 1024 for ONC RPC Version 2." 1026 [Srinivasan-rpc] Srinivasan, R. (1995). RFC 1831, "RPC: Remote 1027 Procedure Call Protocol Specification Version 2." 1029 [Srinivasan-xdr] Srinivasan, R. (1995). RFC 1832, "XDR: External Data 1030 Representation Standard." 1032 10. Authors' Addresses 1034 Michael Eisler 1035 Sun Microsystems, Inc. 1036 M/S UCOS03 1037 2550 Garcia Avenue 1038 Mountain View, CA 94043 1040 Phone: +1 (719) 599-9026 1042 E-mail: mre@eng.sun.com 1044 Alex Chiu 1045 Sun Microsystems, Inc. 1046 M/S UMPK17-203 1047 2550 Garcia Avenue 1048 Mountain View, CA 94043 1050 Phone: +1 (415) 786-6465 1052 E-mail: hacker@eng.sun.com 1054 Lin Ling 1055 Sun Microsystems, Inc. 1056 M/S UMPK17-201 1057 2550 Garcia Avenue 1058 Mountain View, CA 94043 1060 Phone: +1 (415) 786-5084 1062 E-mail: lling@eng.sun.com