1 2 3 4 5 6 7Network Working Group L. Zhu 8Request for Comments: 4121 K. Jaganathan 9Updates: 1964 Microsoft 10Category: Standards Track S. Hartman 11 MIT 12 July 2005 13 14 15 The Kerberos Version 5 16 Generic Security Service Application Program Interface (GSS-API) 17 Mechanism: Version 2 18 19Status of This Memo 20 21 This document specifies an Internet standards track protocol for the 22 Internet community, and requests discussion and suggestions for 23 improvements. Please refer to the current edition of the "Internet 24 Official Protocol Standards" (STD 1) for the standardization state 25 and status of this protocol. Distribution of this memo is unlimited. 26 27Copyright Notice 28 29 Copyright (C) The Internet Society (2005). 30 31Abstract 32 33 This document defines protocols, procedures, and conventions to be 34 employed by peers implementing the Generic Security Service 35 Application Program Interface (GSS-API) when using the Kerberos 36 Version 5 mechanism. 37 38 RFC 1964 is updated and incremental changes are proposed in response 39 to recent developments such as the introduction of Kerberos 40 cryptosystem framework. These changes support the inclusion of new 41 cryptosystems, by defining new per-message tokens along with their 42 encryption and checksum algorithms based on the cryptosystem 43 profiles. 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58Zhu, et al. Standards Track [Page 1] 59 60RFC 4121 Kerberos Version 5 GSS-API July 2005 61 62 63Table of Contents 64 65 1. Introduction ....................................................2 66 2. Key Derivation for Per-Message Tokens ...........................4 67 3. Quality of Protection ...........................................4 68 4. Definitions and Token Formats ...................................5 69 4.1. Context Establishment Tokens ...............................5 70 4.1.1. Authenticator Checksum ..............................6 71 4.2. Per-Message Tokens .........................................9 72 4.2.1. Sequence Number .....................................9 73 4.2.2. Flags Field .........................................9 74 4.2.3. EC Field ...........................................10 75 4.2.4. Encryption and Checksum Operations .................10 76 4.2.5. RRC Field ..........................................11 77 4.2.6. Message Layouts ....................................12 78 4.3. Context Deletion Tokens ...................................13 79 4.4. Token Identifier Assignment Considerations ................13 80 5. Parameter Definitions ..........................................14 81 5.1. Minor Status Codes ........................................14 82 5.1.1. Non-Kerberos-specific Codes ........................14 83 5.1.2. Kerberos-specific Codes ............................15 84 5.2. Buffer Sizes ..............................................15 85 6. Backwards Compatibility Considerations .........................15 86 7. Security Considerations ........................................16 87 8. Acknowledgements................................................17 88 9. References .....................................................18 89 9.1. Normative References ......................................18 90 9.2. Informative References ....................................18 91 921. Introduction 93 94 [RFC3961] defines a generic framework for describing encryption and 95 checksum types to be used with the Kerberos protocol and associated 96 protocols. 97 98 [RFC1964] describes the GSS-API mechanism for Kerberos Version 5. It 99 defines the format of context establishment, per-message and context 100 deletion tokens, and uses algorithm identifiers for each cryptosystem 101 in per-message and context deletion tokens. 102 103 The approach taken in this document obviates the need for algorithm 104 identifiers. This is accomplished by using the same encryption 105 algorithm, specified by the crypto profile [RFC3961] for the session 106 key or subkey that is created during context negotiation, and its 107 required checksum algorithm. Message layouts of the per-message 108 tokens are therefore revised to remove algorithm indicators and to 109 add extra information to support the generic crypto framework 110 [RFC3961]. 111 112 113 114Zhu, et al. Standards Track [Page 2] 115 116RFC 4121 Kerberos Version 5 GSS-API July 2005 117 118 119 Tokens transferred between GSS-API peers for security context 120 establishment are also described in this document. The data elements 121 exchanged between a GSS-API endpoint implementation and the Kerberos 122 Key Distribution Center (KDC) [RFC4120] are not specific to GSS-API 123 usage and are therefore defined within [RFC4120] rather than this 124 specification. 125 126 The new token formats specified in this document MUST be used with 127 all "newer" encryption types [RFC4120] and MAY be used with 128 encryption types that are not "newer", provided that the initiator 129 and acceptor know from the context establishment that they can both 130 process these new token formats. 131 132 "Newer" encryption types are those which have been specified along 133 with or since the new Kerberos cryptosystem specification [RFC3961], 134 as defined in section 3.1.3 of [RFC4120]. The list of not-newer 135 encryption types is as follows [RFC3961]: 136 137 Encryption Type Assigned Number 138 ---------------------------------------------- 139 des-cbc-crc 1 140 des-cbc-md4 2 141 des-cbc-md5 3 142 des3-cbc-md5 5 143 des3-cbc-sha1 7 144 dsaWithSHA1-CmsOID 9 145 md5WithRSAEncryption-CmsOID 10 146 sha1WithRSAEncryption-CmsOID 11 147 rc2CBC-EnvOID 12 148 rsaEncryption-EnvOID 13 149 rsaES-OAEP-ENV-OID 14 150 des-ede3-cbc-Env-OID 15 151 des3-cbc-sha1-kd 16 152 rc4-hmac 23 153 154 Conventions used in this document 155 156 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 157 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 158 document are to be interpreted as described in [RFC2119]. 159 160 The term "little-endian order" is used for brevity to refer to the 161 least-significant-octet-first encoding, while the term "big-endian 162 order" is for the most-significant-octet-first encoding. 163 164 165 166 167 168 169 170Zhu, et al. Standards Track [Page 3] 171 172RFC 4121 Kerberos Version 5 GSS-API July 2005 173 174 1752. Key Derivation for Per-Message Tokens 176 177 To limit the exposure of a given key, [RFC3961] adopted "one-way" 178 "entropy-preserving" derived keys, from a base key or protocol key, 179 for different purposes or key usages. 180 181 This document defines four key usage values below that are used to 182 derive a specific key for signing and sealing messages from the 183 session key or subkey [RFC4120] created during the context 184 establishment. 185 186 Name Value 187 ------------------------------------- 188 KG-USAGE-ACCEPTOR-SEAL 22 189 KG-USAGE-ACCEPTOR-SIGN 23 190 KG-USAGE-INITIATOR-SEAL 24 191 KG-USAGE-INITIATOR-SIGN 25 192 193 When the sender is the context acceptor, KG-USAGE-ACCEPTOR-SIGN is 194 used as the usage number in the key derivation function for deriving 195 keys to be used in MIC tokens (as defined in section 4.2.6.1). 196 KG-USAGE-ACCEPTOR-SEAL is used for Wrap tokens (as defined in section 197 4.2.6.2). Similarly, when the sender is the context initiator, 198 KG-USAGE-INITIATOR-SIGN is used as the usage number in the key 199 derivation function for MIC tokens, while KG-USAGE-INITIATOR-SEAL is 200 used for Wrap tokens. Even if the Wrap token does not provide for 201 confidentiality, the same usage values specified above are used. 202 203 During the context initiation and acceptance sequence, the acceptor 204 MAY assert a subkey in the AP-REP message. If the acceptor asserts a 205 subkey, the base key is the acceptor-asserted subkey and subsequent 206 per-message tokens MUST be flagged with "AcceptorSubkey", as 207 described in section 4.2.2. Otherwise, if the initiator asserts a 208 subkey in the AP-REQ message, the base key is this subkey; if the 209 initiator does not assert a subkey, the base key is the session key 210 in the service ticket. 211 2123. Quality of Protection 213 214 The GSS-API specification [RFC2743] provides Quality of Protection 215 (QOP) values that can be used by applications to request a certain 216 type of encryption or signing. A zero QOP value is used to indicate 217 the "default" protection; applications that do not use the default 218 QOP are not guaranteed to be portable across implementations, or even 219 to inter-operate with different deployment configurations of the same 220 implementation. Using a different algorithm than the one for which 221 the key is defined may not be appropriate. Therefore, when the new 222 method in this document is used, the QOP value is ignored. 223 224 225 226Zhu, et al. Standards Track [Page 4] 227 228RFC 4121 Kerberos Version 5 GSS-API July 2005 229 230 231 The encryption and checksum algorithms in per-message tokens are now 232 implicitly defined by the algorithms associated with the session key 233 or subkey. Therefore, algorithm identifiers as described in 234 [RFC1964] are no longer needed and are removed from the new token 235 headers. 236 2374. Definitions and Token Formats 238 239 This section provides terms and definitions, as well as descriptions 240 for tokens specific to the Kerberos Version 5 GSS-API mechanism. 241 2424.1. Context Establishment Tokens 243 244 All context establishment tokens emitted by the Kerberos Version 5 245 GSS-API mechanism SHALL have the framing described in section 3.1 of 246 [RFC2743], as illustrated by the following pseudo-ASN.1 structures: 247 248 GSS-API DEFINITIONS ::= 249 250 BEGIN 251 252 MechType ::= OBJECT IDENTIFIER 253 -- representing Kerberos V5 mechanism 254 255 GSSAPI-Token ::= 256 -- option indication (delegation, etc.) indicated within 257 -- mechanism-specific token 258 [APPLICATION 0] IMPLICIT SEQUENCE { 259 thisMech MechType, 260 innerToken ANY DEFINED BY thisMech 261 -- contents mechanism-specific 262 -- ASN.1 structure not required 263 } 264 265 END 266 267 The innerToken field starts with a two-octet token-identifier 268 (TOK_ID) expressed in big-endian order, followed by a Kerberos 269 message. 270 271 Following are the TOK_ID values used in the context establishment 272 tokens: 273 274 Token TOK_ID Value in Hex 275 ----------------------------------------- 276 KRB_AP_REQ 01 00 277 KRB_AP_REP 02 00 278 KRB_ERROR 03 00 279 280 281 282Zhu, et al. Standards Track [Page 5] 283 284RFC 4121 Kerberos Version 5 GSS-API July 2005 285 286 287 Where Kerberos message KRB_AP_REQUEST, KRB_AP_REPLY, and KRB_ERROR 288 are defined in [RFC4120]. 289 290 If an unknown token identifier (TOK_ID) is received in the initial 291 context establishment token, the receiver MUST return 292 GSS_S_CONTINUE_NEEDED major status, and the returned output token 293 MUST contain a KRB_ERROR message with the error code 294 KRB_AP_ERR_MSG_TYPE [RFC4120]. 295 2964.1.1. Authenticator Checksum 297 298 The authenticator in the KRB_AP_REQ message MUST include the optional 299 sequence number and the checksum field. The checksum field is used 300 to convey service flags, channel bindings, and optional delegation 301 information. 302 303 The checksum type MUST be 0x8003. When delegation is used, a 304 ticket-granting ticket will be transferred in a KRB_CRED message. 305 This ticket SHOULD have its forwardable flag set. The EncryptedData 306 field of the KRB_CRED message [RFC4120] MUST be encrypted in the 307 session key of the ticket used to authenticate the context. 308 309 The authenticator checksum field SHALL have the following format: 310 311 Octet Name Description 312 ----------------------------------------------------------------- 313 0..3 Lgth Number of octets in Bnd field; Represented 314 in little-endian order; Currently contains 315 hex value 10 00 00 00 (16). 316 4..19 Bnd Channel binding information, as described in 317 section 4.1.1.2. 318 20..23 Flags Four-octet context-establishment flags in 319 little-endian order as described in section 320 4.1.1.1. 321 24..25 DlgOpt The delegation option identifier (=1) in 322 little-endian order [optional]. This field 323 and the next two fields are present if and 324 only if GSS_C_DELEG_FLAG is set as described 325 in section 4.1.1.1. 326 26..27 Dlgth The length of the Deleg field in 327 little-endian order [optional]. 328 28..(n-1) Deleg A KRB_CRED message (n = Dlgth + 28) 329 [optional]. 330 n..last Exts Extensions [optional]. 331 332 The length of the checksum field MUST be at least 24 octets when 333 GSS_C_DELEG_FLAG is not set (as described in section 4.1.1.1), and at 334 least 28 octets plus Dlgth octets when GSS_C_DELEG_FLAG is set. When 335 336 337 338Zhu, et al. Standards Track [Page 6] 339 340RFC 4121 Kerberos Version 5 GSS-API July 2005 341 342 343 GSS_C_DELEG_FLAG is set, the DlgOpt, Dlgth, and Deleg fields of the 344 checksum data MUST immediately follow the Flags field. The optional 345 trailing octets (namely the "Exts" field) facilitate future 346 extensions to this mechanism. When delegation is not used, but the 347 Exts field is present, the Exts field starts at octet 24 (DlgOpt, 348 Dlgth and Deleg are absent). 349 350 Initiators that do not support the extensions MUST NOT include more 351 than 24 octets in the checksum field (when GSS_C_DELEG_FLAG is not 352 set) or more than 28 octets plus the KRB_CRED in the Deleg field 353 (when GSS_C_DELEG_FLAG is set). Acceptors that do not understand the 354 355 Extensions MUST ignore any octets past the Deleg field of the 356 checksum data (when GSS_C_DELEG_FLAG is set) or past the Flags field 357 of the checksum data (when GSS_C_DELEG_FLAG is not set). 358 3594.1.1.1. Checksum Flags Field 360 361 The checksum "Flags" field is used to convey service options or 362 extension negotiation information. 363 364 The following context establishment flags are defined in [RFC2744]. 365 366 Flag Name Value 367 --------------------------------- 368 GSS_C_DELEG_FLAG 1 369 GSS_C_MUTUAL_FLAG 2 370 GSS_C_REPLAY_FLAG 4 371 GSS_C_SEQUENCE_FLAG 8 372 GSS_C_CONF_FLAG 16 373 GSS_C_INTEG_FLAG 32 374 375 Context establishment flags are exposed to the calling application. 376 If the calling application desires a particular service option, then 377 it requests that option via GSS_Init_sec_context() [RFC2743]. If the 378 corresponding return state values [RFC2743] indicate that any of the 379 above optional context level services will be active on the context, 380 the corresponding flag values in the table above MUST be set in the 381 checksum Flags field. 382 383 Flag values 4096..524288 (2^12, 2^13, ..., 2^19) are reserved for use 384 with legacy vendor-specific extensions to this mechanism. 385 386 387 388 389 390 391 392 393 394Zhu, et al. Standards Track [Page 7] 395 396RFC 4121 Kerberos Version 5 GSS-API July 2005 397 398 399 All other flag values not specified herein are reserved for future 400 use. Future revisions of this mechanism may use these reserved flags 401 and may rely on implementations of this version to not use such flags 402 in order to properly negotiate mechanism versions. Undefined flag 403 values MUST be cleared by the sender, and unknown flags MUST be 404 ignored by the receiver. 405 4064.1.1.2. Channel Binding Information 407 408 These tags are intended to be used to identify the particular 409 communications channel for which the GSS-API security context 410 establishment tokens are intended, thus limiting the scope within 411 which an intercepted context establishment token can be reused by an 412 attacker (see [RFC2743], section 1.1.6). 413 414 When using C language bindings, channel bindings are communicated to 415 the GSS-API using the following structure [RFC2744]: 416 417 typedef struct gss_channel_bindings_struct { 418 OM_uint32 initiator_addrtype; 419 gss_buffer_desc initiator_address; 420 OM_uint32 acceptor_addrtype; 421 gss_buffer_desc acceptor_address; 422 gss_buffer_desc application_data; 423 } *gss_channel_bindings_t; 424 425 The member fields and constants used for different address types are 426 defined in [RFC2744]. 427 428 The "Bnd" field contains the MD5 hash of channel bindings, taken over 429 all non-null components of bindings, in order of declaration. 430 Integer fields within channel bindings are represented in little- 431 endian order for the purposes of the MD5 calculation. 432 433 In computing the contents of the Bnd field, the following detailed 434 points apply: 435 436 (1) For purposes of MD5 hash computation, each integer field and 437 input length field SHALL be formatted into four octets, using 438 little-endian octet ordering. 439 440 (2) All input length fields within gss_buffer_desc elements of a 441 gss_channel_bindings_struct even those which are zero-valued, 442 SHALL be included in the hash calculation. The value elements of 443 gss_buffer_desc elements SHALL be dereferenced, and the resulting 444 data SHALL be included within the hash computation, only for the 445 case of gss_buffer_desc elements having non-zero length 446 specifiers. 447 448 449 450Zhu, et al. Standards Track [Page 8] 451 452RFC 4121 Kerberos Version 5 GSS-API July 2005 453 454 455 (3) If the caller passes the value GSS_C_NO_BINDINGS instead of a 456 valid channel binding structure, the Bnd field SHALL be set to 16 457 zero-valued octets. 458 459 If the caller to GSS_Accept_sec_context [RFC2743] passes in 460 GSS_C_NO_CHANNEL_BINDINGS [RFC2744] as the channel bindings, then the 461 acceptor MAY ignore any channel bindings supplied by the initiator, 462 returning success even if the initiator did pass in channel bindings. 463 464 If the application supplies, in the channel bindings, a buffer with a 465 length field larger than 4294967295 (2^32 - 1), the implementation of 466 this mechanism MAY choose to reject the channel bindings altogether, 467 using major status GSS_S_BAD_BINDINGS [RFC2743]. In any case, the 468 size of channel-binding data buffers that can be used (interoperable, 469 without extensions) with this specification is limited to 4294967295 470 octets. 471 4724.2. Per-Message Tokens 473 474 Two classes of tokens are defined in this section: (1) "MIC" tokens, 475 emitted by calls to GSS_GetMIC() and consumed by calls to 476 GSS_VerifyMIC(), and (2) "Wrap" tokens, emitted by calls to 477 GSS_Wrap() and consumed by calls to GSS_Unwrap(). 478 479 These new per-message tokens do not include the generic GSS-API token 480 framing used by the context establishment tokens. These new tokens 481 are designed to be used with newer crypto systems that can have 482 variable-size checksums. 483 4844.2.1. Sequence Number 485 486 To distinguish intentionally-repeated messages from maliciously- 487 replayed ones, per-message tokens contain a sequence number field, 488 which is a 64 bit integer expressed in big-endian order. After 489 sending a GSS_GetMIC() or GSS_Wrap() token, the sender's sequence 490 numbers SHALL be incremented by one. 491 4924.2.2. Flags Field 493 494 The "Flags" field is a one-octet integer used to indicate a set of 495 attributes for the protected message. For example, one flag is 496 allocated as the direction-indicator, thus preventing the acceptance 497 of the same message sent back in the reverse direction by an 498 adversary. 499 500 501 502 503 504 505 506Zhu, et al. Standards Track [Page 9] 507 508RFC 4121 Kerberos Version 5 GSS-API July 2005 509 510 511 The meanings of bits in this field (the least significant bit is bit 512 0) are as follows: 513 514 Bit Name Description 515 -------------------------------------------------------------- 516 0 SentByAcceptor When set, this flag indicates the sender 517 is the context acceptor. When not set, 518 it indicates the sender is the context 519 initiator. 520 1 Sealed When set in Wrap tokens, this flag 521 indicates confidentiality is provided 522 for. It SHALL NOT be set in MIC tokens. 523 2 AcceptorSubkey A subkey asserted by the context acceptor 524 is used to protect the message. 525 526 The rest of available bits are reserved for future use and MUST be 527 cleared. The receiver MUST ignore unknown flags. 528 5294.2.3. EC Field 530 531 The "EC" (Extra Count) field is a two-octet integer field expressed 532 in big-endian order. 533 534 In Wrap tokens with confidentiality, the EC field SHALL be used to 535 encode the number of octets in the filler, as described in section 536 4.2.4. 537 538 In Wrap tokens without confidentiality, the EC field SHALL be used to 539 encode the number of octets in the trailing checksum, as described in 540 section 4.2.4. 541 5424.2.4. Encryption and Checksum Operations 543 544 The encryption algorithms defined by the crypto profiles provide for 545 integrity protection [RFC3961]. Therefore, no separate checksum is 546 needed. 547 548 The result of decryption can be longer than the original plaintext 549 [RFC3961] and the extra trailing octets are called "crypto-system 550 residue" in this document. However, given the size of any plaintext 551 data, one can always find a (possibly larger) size, such that when 552 padding the to-be-encrypted text to that size, there will be no 553 crypto-system residue added [RFC3961]. 554 555 In Wrap tokens that provide for confidentiality, the first 16 octets 556 of the Wrap token (the "header", as defined in section 4.2.6), SHALL 557 be appended to the plaintext data before encryption. Filler octets 558 MAY be inserted between the plaintext data and the "header." The 559 560 561 562Zhu, et al. Standards Track [Page 10] 563 564RFC 4121 Kerberos Version 5 GSS-API July 2005 565 566 567 values and size of the filler octets are chosen by implementations, 568 such that there SHALL be no crypto-system residue present after the 569 decryption. The resulting Wrap token is {"header" | 570 encrypt(plaintext-data | filler | "header")}, where encrypt() is the 571 encryption operation (which provides for integrity protection) 572 defined in the crypto profile [RFC3961], and the RRC field (as 573 defined in section 4.2.5) in the to-be-encrypted header contains the 574 hex value 00 00. 575 576 In Wrap tokens that do not provide for confidentiality, the checksum 577 SHALL be calculated first over the to-be-signed plaintext data, and 578 then over the first 16 octets of the Wrap token (the "header", as 579 defined in section 4.2.6). Both the EC field and the RRC field in 580 the token header SHALL be filled with zeroes for the purpose of 581 calculating the checksum. The resulting Wrap token is {"header" | 582 plaintext-data | get_mic(plaintext-data | "header")}, where get_mic() 583 is the checksum operation for the required checksum mechanism of the 584 chosen encryption mechanism defined in the crypto profile [RFC3961]. 585 586 The parameters for the key and the cipher-state in the encrypt() and 587 get_mic() operations have been omitted for brevity. 588 589 For MIC tokens, the checksum SHALL be calculated as follows: the 590 checksum operation is calculated first over the to-be-signed 591 plaintext data, and then over the first 16 octets of the MIC token, 592 where the checksum mechanism is the required checksum mechanism of 593 the chosen encryption mechanism defined in the crypto profile 594 [RFC3961]. 595 596 The resulting Wrap and MIC tokens bind the data to the token header, 597 including the sequence number and the direction indicator. 598 5994.2.5. RRC Field 600 601 The "RRC" (Right Rotation Count) field in Wrap tokens is added to 602 allow the data to be encrypted in-place by existing SSPI (Security 603 Service Provider Interface) [SSPI] applications that do not provide 604 an additional buffer for the trailer (the cipher text after the in- 605 place-encrypted data) in addition to the buffer for the header (the 606 cipher text before the in-place-encrypted data). Excluding the first 607 16 octets of the token header, the resulting Wrap token in the 608 previous section is rotated to the right by "RRC" octets. The net 609 result is that "RRC" octets of trailing octets are moved toward the 610 header. 611 612 Consider the following as an example of this rotation operation: 613 Assume that the RRC value is 3 and the token before the rotation is 614 {"header" | aa | bb | cc | dd | ee | ff | gg | hh}. The token after 615 616 617 618Zhu, et al. Standards Track [Page 11] 619 620RFC 4121 Kerberos Version 5 GSS-API July 2005 621 622 623 rotation would be {"header" | ff | gg | hh | aa | bb | cc | dd | ee 624 }, where {aa | bb | cc |...| hh} would be used to indicate the octet 625 sequence. 626 627 The RRC field is expressed as a two-octet integer in big-endian 628 order. 629 630 The rotation count value is chosen by the sender based on 631 implementation details. The receiver MUST be able to interpret all 632 possible rotation count values, including rotation counts greater 633 than the length of the token. 634 6354.2.6. Message Layouts 636 637 Per-message tokens start with a two-octet token identifier (TOK_ID) 638 field, expressed in big-endian order. These tokens are defined 639 separately in the following sub-sections. 640 6414.2.6.1. MIC Tokens 642 643 Use of the GSS_GetMIC() call yields a token (referred as the MIC 644 token in this document), separate from the user data being protected, 645 which can be used to verify the integrity of that data as received. 646 The token has the following format: 647 648 Octet no Name Description 649 -------------------------------------------------------------- 650 0..1 TOK_ID Identification field. Tokens emitted by 651 GSS_GetMIC() contain the hex value 04 04 652 expressed in big-endian order in this 653 field. 654 2 Flags Attributes field, as described in section 655 4.2.2. 656 3..7 Filler Contains five octets of hex value FF. 657 8..15 SND_SEQ Sequence number field in clear text, 658 expressed in big-endian order. 659 16..last SGN_CKSUM Checksum of the "to-be-signed" data and 660 octet 0..15, as described in section 4.2.4. 661 662 The Filler field is included in the checksum calculation for 663 simplicity. 664 665 666 667 668 669 670 671 672 673 674Zhu, et al. Standards Track [Page 12] 675 676RFC 4121 Kerberos Version 5 GSS-API July 2005 677 678 6794.2.6.2. Wrap Tokens 680 681 Use of the GSS_Wrap() call yields a token (referred as the Wrap token 682 in this document), which consists of a descriptive header, followed 683 by a body portion that contains either the input user data in 684 plaintext concatenated with the checksum, or the input user data 685 encrypted. The GSS_Wrap() token SHALL have the following format: 686 687 Octet no Name Description 688 -------------------------------------------------------------- 689 0..1 TOK_ID Identification field. Tokens emitted by 690 GSS_Wrap() contain the hex value 05 04 691 expressed in big-endian order in this 692 field. 693 2 Flags Attributes field, as described in section 694 4.2.2. 695 3 Filler Contains the hex value FF. 696 4..5 EC Contains the "extra count" field, in big- 697 endian order as described in section 4.2.3. 698 6..7 RRC Contains the "right rotation count" in big- 699 endian order, as described in section 700 4.2.5. 701 8..15 SND_SEQ Sequence number field in clear text, 702 expressed in big-endian order. 703 16..last Data Encrypted data for Wrap tokens with 704 confidentiality, or plaintext data followed 705 by the checksum for Wrap tokens without 706 confidentiality, as described in section 707 4.2.4. 708 7094.3. Context Deletion Tokens 710 711 Context deletion tokens are empty in this mechanism. Both peers to a 712 security context invoke GSS_Delete_sec_context() [RFC2743] 713 independently, passing a null output_context_token buffer to indicate 714 that no context_token is required. Implementations of 715 GSS_Delete_sec_context() should delete relevant locally-stored 716 context information. 717 7184.4. Token Identifier Assignment Considerations 719 720 Token identifiers (TOK_ID) from 0x60 0x00 through 0x60 0xFF inclusive 721 are reserved and SHALL NOT be assigned. Thus, by examining the first 722 two octets of a token, one can tell unambiguously if it is wrapped 723 with the generic GSS-API token framing. 724 725 726 727 728 729 730Zhu, et al. Standards Track [Page 13] 731 732RFC 4121 Kerberos Version 5 GSS-API July 2005 733 734 7355. Parameter Definitions 736 737 This section defines parameter values used by the Kerberos V5 GSS-API 738 mechanism. It defines interface elements that support portability, 739 and assumes use of C language bindings per [RFC2744]. 740 7415.1. Minor Status Codes 742 743 This section recommends common symbolic names for minor_status values 744 to be returned by the Kerberos V5 GSS-API mechanism. Use of these 745 definitions will enable independent implementers to enhance 746 application portability across different implementations of the 747 mechanism defined in this specification. (In all cases, 748 implementations of GSS_Display_status() will enable callers to 749 convert minor_status indicators to text representations.) Each 750 implementation should make available, through include files or other 751 means, a facility to translate these symbolic names into the concrete 752 values that a particular GSS-API implementation uses to represent the 753 minor_status values specified in this section. 754 755 This list may grow over time and the need for additional minor_status 756 codes, specific to particular implementations, may arise. However, 757 it is recommended that implementations should return a minor_status 758 value as defined on a mechanism-wide basis within this section when 759 that code accurately represents reportable status rather than using a 760 separate, implementation-defined code. 761 7625.1.1. Non-Kerberos-specific Codes 763 764 GSS_KRB5_S_G_BAD_SERVICE_NAME 765 /* "No @ in SERVICE-NAME name string" */ 766 GSS_KRB5_S_G_BAD_STRING_UID 767 /* "STRING-UID-NAME contains nondigits" */ 768 GSS_KRB5_S_G_NOUSER 769 /* "UID does not resolve to username" */ 770 GSS_KRB5_S_G_VALIDATE_FAILED 771 /* "Validation error" */ 772 GSS_KRB5_S_G_BUFFER_ALLOC 773 /* "Couldn't allocate gss_buffer_t data" */ 774 GSS_KRB5_S_G_BAD_MSG_CTX 775 /* "Message context invalid" */ 776 GSS_KRB5_S_G_WRONG_SIZE 777 /* "Buffer is the wrong size" */ 778 GSS_KRB5_S_G_BAD_USAGE 779 /* "Credential usage type is unknown" */ 780 GSS_KRB5_S_G_UNKNOWN_QOP 781 /* "Unknown quality of protection specified" */ 782 783 784 785 786Zhu, et al. Standards Track [Page 14] 787 788RFC 4121 Kerberos Version 5 GSS-API July 2005 789 790 7915.1.2. Kerberos-specific Codes 792 793 GSS_KRB5_S_KG_CCACHE_NOMATCH 794 /* "Client principal in credentials does not match 795 specified name" */ 796 GSS_KRB5_S_KG_KEYTAB_NOMATCH 797 /* "No key available for specified service 798 principal" */ 799 GSS_KRB5_S_KG_TGT_MISSING 800 /* "No Kerberos ticket-granting ticket available" */ 801 GSS_KRB5_S_KG_NO_SUBKEY 802 /* "Authenticator has no subkey" */ 803 GSS_KRB5_S_KG_CONTEXT_ESTABLISHED 804 /* "Context is already fully established" */ 805 GSS_KRB5_S_KG_BAD_SIGN_TYPE 806 /* "Unknown signature type in token" */ 807 GSS_KRB5_S_KG_BAD_LENGTH 808 /* "Invalid field length in token" */ 809 GSS_KRB5_S_KG_CTX_INCOMPLETE 810 /* "Attempt to use incomplete security context" */ 811 8125.2. Buffer Sizes 813 814 All implementations of this specification MUST be capable of 815 accepting buffers of at least 16K octets as input to GSS_GetMIC(), 816 GSS_VerifyMIC(), and GSS_Wrap(). They MUST also be capable of 817 accepting the output_token generated by GSS_Wrap() for a 16K octet 818 input buffer as input to GSS_Unwrap(). Implementations SHOULD 819 support 64K octet input buffers, and MAY support even larger input 820 buffer sizes. 821 8226. Backwards Compatibility Considerations 823 824 The new token formats defined in this document will only be 825 recognized by new implementations. To address this, implementations 826 can always use the explicit sign or seal algorithm in [RFC1964] when 827 the key type corresponds to not "newer" enctypes. As an alternative, 828 one might retry sending the message with the sign or seal algorithm 829 explicitly defined as in [RFC1964]. However, this would require 830 either the use of a mechanism such as [RFC2478] to securely negotiate 831 the method, or the use of an out-of-band mechanism to choose the 832 appropriate mechanism. For this reason, it is RECOMMENDED that the 833 new token formats defined in this document SHOULD be used only if 834 both peers are known to support the new mechanism during context 835 negotiation because of, for example, the use of "new" enctypes. 836 837 838 839 840 841 842Zhu, et al. Standards Track [Page 15] 843 844RFC 4121 Kerberos Version 5 GSS-API July 2005 845 846 847 GSS_Unwrap() or GSS_VerifyMIC() can process a message token as 848 follows: it can look at the first octet of the token header, and if 849 it is 0x60, then the token must carry the generic GSS-API pseudo 850 ASN.1 framing. Otherwise, the first two octets of the token contain 851 the TOK_ID that uniquely identify the token message format. 852 8537. Security Considerations 854 855 Channel bindings are validated by the acceptor. The acceptor can 856 ignore the channel bindings restriction supplied by the initiator and 857 carried in the authenticator checksum, if (1) channel bindings are 858 not used by GSS_Accept_sec_context [RFC2743], and (2) the acceptor 859 does not prove to the initiator that it has the same channel bindings 860 as the initiator (even if the client requested mutual 861 authentication). This limitation should be considered by designers 862 of applications that would use channel bindings, whether to limit the 863 use of GSS-API contexts to nodes with specific network addresses, to 864 authenticate other established, secure channels using Kerberos 865 Version 5, or for any other purpose. 866 867 Session key types are selected by the KDC. Under the current 868 mechanism, no negotiation of algorithm types occurs, so server-side 869 (acceptor) implementations cannot request that clients not use 870 algorithm types not understood by the server. However, 871 administrators can control what enctypes can be used for session keys 872 for this mechanism by controlling the set of the ticket session key 873 enctypes which the KDC is willing to use in tickets for a given 874 acceptor principal. Therefore, the KDC could be given the task of 875 limiting session keys for a given service to types actually supported 876 by the Kerberos and GSSAPI software on the server. This has a 877 drawback for cases in which a service principal name is used for both 878 GSSAPI-based and non-GSSAPI-based communication (most notably the 879 "host" service key), if the GSSAPI implementation does not understand 880 (for example) AES [RFC3962], but the Kerberos implementation does. 881 This means that AES session keys cannot be issued for that service 882 principal, which keeps the protection of non-GSSAPI services weaker 883 than necessary. KDC administrators desiring to limit the session key 884 types to support interoperability with such GSSAPI implementations 885 should carefully weigh the reduction in protection offered by such 886 mechanisms against the benefits of interoperability. 887 888 889 890 891 892 893 894 895 896 897 898Zhu, et al. Standards Track [Page 16] 899 900RFC 4121 Kerberos Version 5 GSS-API July 2005 901 902 9038. Acknowledgements 904 905 Ken Raeburn and Nicolas Williams corrected many of our errors in the 906 use of generic profiles and were instrumental in the creation of this 907 document. 908 909 The text for security considerations was contributed by Nicolas 910 Williams and Ken Raeburn. 911 912 Sam Hartman and Ken Raeburn suggested the "floating trailer" idea, 913 namely the encoding of the RRC field. 914 915 Sam Hartman and Nicolas Williams recommended the replacing our 916 earlier key derivation function for directional keys with different 917 key usage numbers for each direction as well as retaining the 918 directional bit for maximum compatibility. 919 920 Paul Leach provided numerous suggestions and comments. 921 922 Scott Field, Richard Ward, Dan Simon, Kevin Damour, and Simon 923 Josefsson also provided valuable inputs on this document. 924 925 Jeffrey Hutzelman provided comments and clarifications for the text 926 related to the channel bindings. 927 928 Jeffrey Hutzelman and Russ Housley suggested many editorial changes. 929 930 Luke Howard provided implementations of this document for the Heimdal 931 code base, and helped inter-operability testing with the Microsoft 932 code base, together with Love Hornquist Astrand. These experiments 933 formed the basis of this document. 934 935 Martin Rex provided suggestions of TOK_ID assignment recommendations, 936 thus the token tagging in this document is unambiguous if the token 937 is wrapped with the pseudo ASN.1 header. 938 939 John Linn wrote the original Kerberos Version 5 mechanism 940 specification [RFC1964], of which some text has been retained. 941 942 943 944 945 946 947 948 949 950 951 952 953 954Zhu, et al. Standards Track [Page 17] 955 956RFC 4121 Kerberos Version 5 GSS-API July 2005 957 958 9599. References 960 9619.1. Normative References 962 963 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 964 Requirement Levels", BCP 14, RFC 2119, March 1997. 965 966 [RFC2743] Linn, J., "Generic Security Service Application Program 967 Interface Version 2, Update 1", RFC 2743, January 2000. 968 969 [RFC2744] Wray, J., "Generic Security Service API Version 2: 970 C-bindings", RFC 2744, January 2000. 971 972 [RFC1964] Linn, J., "The Kerberos Version 5 GSS-API Mechanism", RFC 973 1964, June 1996. 974 975 [RFC3961] Raeburn, K., "Encryption and Checksum Specifications for 976 Kerberos 5", RFC 3961, February 2005. 977 978 [RFC4120] Neuman, C., Yu, T., Hartman, S., and K. Raeburn, "The 979 Kerberos Network Authentication Service (V5)", RFC 4120, 980 July 2005. 981 9829.2. Informative References 983 984 [SSPI] Leach, P., "Security Service Provider Interface", 985 Microsoft Developer Network (MSDN), April 2003. 986 987 [RFC3962] Raeburn, K., "Advanced Encryption Standard (AES) 988 Encryption for Kerberos 5", RFC 3962, February 2005. 989 990 [RFC2478] Baize, E. and D. Pinkas, "The Simple and Protected GSS-API 991 Negotiation Mechanism", RFC 2478, December 1998. 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010Zhu, et al. Standards Track [Page 18] 1011 1012RFC 4121 Kerberos Version 5 GSS-API July 2005 1013 1014 1015Authors' Addresses 1016 1017 Larry Zhu 1018 One Microsoft Way 1019 Redmond, WA 98052 - USA 1020 1021 EMail: LZhu@microsoft.com 1022 1023 1024 Karthik Jaganathan 1025 One Microsoft Way 1026 Redmond, WA 98052 - USA 1027 1028 EMail: karthikj@microsoft.com 1029 1030 1031 Sam Hartman 1032 Massachusetts Institute of Technology 1033 77 Massachusetts Avenue 1034 Cambridge, MA 02139 - USA 1035 1036 EMail: hartmans-ietf@mit.edu 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066Zhu, et al. Standards Track [Page 19] 1067 1068RFC 4121 Kerberos Version 5 GSS-API July 2005 1069 1070 1071Full Copyright Statement 1072 1073 Copyright (C) The Internet Society (2005). 1074 1075 This document is subject to the rights, licenses and restrictions 1076 contained in BCP 78, and except as set forth therein, the authors 1077 retain all their rights. 1078 1079 This document and the information contained herein are provided on an 1080 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 1081 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 1082 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 1083 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 1084 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 1085 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1086 1087Intellectual Property 1088 1089 The IETF takes no position regarding the validity or scope of any 1090 Intellectual Property Rights or other rights that might be claimed to 1091 pertain to the implementation or use of the technology described in 1092 this document or the extent to which any license under such rights 1093 might or might not be available; nor does it represent that it has 1094 made any independent effort to identify any such rights. Information 1095 on the procedures with respect to rights in RFC documents can be 1096 found in BCP 78 and BCP 79. 1097 1098 Copies of IPR disclosures made to the IETF Secretariat and any 1099 assurances of licenses to be made available, or the result of an 1100 attempt made to obtain a general license or permission for the use of 1101 such proprietary rights by implementers or users of this 1102 specification can be obtained from the IETF on-line IPR repository at 1103 http://www.ietf.org/ipr. 1104 1105 The IETF invites any interested party to bring to its attention any 1106 copyrights, patents or patent applications, or other proprietary 1107 rights that may cover technology that may be required to implement 1108 this standard. Please address the information to the IETF at ietf- 1109 ipr@ietf.org. 1110 1111Acknowledgement 1112 1113 Funding for the RFC Editor function is currently provided by the 1114 Internet Society. 1115 1116 1117 1118 1119 1120 1121 1122Zhu, et al. Standards Track [Page 20] 1123 1124