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