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