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