1 2 3 4 5 6 7Network Working Group J. Linn 8Request for Comments: 1964 OpenVision Technologies 9Category: Standards Track June 1996 10 11 12 The Kerberos Version 5 GSS-API Mechanism 13 14Status of this Memo 15 16 This document specifies an Internet standards track protocol for the 17 Internet community, and requests discussion and suggestions for 18 improvements. Please refer to the current edition of the "Internet 19 Official Protocol Standards" (STD 1) for the standardization state 20 and status of this protocol. Distribution of this memo is unlimited. 21 22ABSTRACT 23 24 This specification defines protocols, procedures, and conventions to 25 be employed by peers implementing the Generic Security Service 26 Application Program Interface (as specified in RFCs 1508 and 1509) 27 when using Kerberos Version 5 technology (as specified in RFC 1510). 28 29ACKNOWLEDGMENTS 30 31 Much of the material in this memo is based on working documents 32 drafted by John Wray of Digital Equipment Corporation and on 33 discussions, implementation activities, and interoperability testing 34 involving Marc Horowitz, Ted Ts'o, and John Wray. Particular thanks 35 are due to each of these individuals for their contributions towards 36 development and availability of GSS-API support within the Kerberos 37 Version 5 code base. 38 391. Token Formats 40 41 This section discusses protocol-visible characteristics of the GSS- 42 API mechanism to be implemented atop Kerberos V5 security technology 43 per RFC-1508 and RFC-1510; it defines elements of protocol for 44 interoperability and is independent of language bindings per RFC- 45 1509. 46 47 Tokens transferred between GSS-API peers (for security context 48 management and per-message protection purposes) are defined. The 49 data elements exchanged between a GSS-API endpoint implementation and 50 the Kerberos KDC are not specific to GSS-API usage and are therefore 51 defined within RFC-1510 rather than within this specification. 52 53 54 55 56 57 58Linn Standards Track [Page 1] 59 60RFC 1964 Kerberos Version 5 GSS-API June 1996 61 62 63 To support ongoing experimentation, testing, and evolution of the 64 specification, the Kerberos V5 GSS-API mechanism as defined in this 65 and any successor memos will be identified with the following Object 66 Identifier, as defined in RFC-1510, until the specification is 67 advanced to the level of Proposed Standard RFC: 68 69 {iso(1), org(3), dod(5), internet(1), security(5), kerberosv5(2)} 70 71 Upon advancement to the level of Proposed Standard RFC, the Kerberos 72 V5 GSS-API mechanism will be identified by an Object Identifier 73 having the value: 74 75 {iso(1) member-body(2) United States(840) mit(113554) infosys(1) 76 gssapi(2) krb5(2)} 77 781.1. Context Establishment Tokens 79 80 Per RFC-1508, Appendix B, the initial context establishment token 81 will be enclosed within framing as follows: 82 83 InitialContextToken ::= 84 [APPLICATION 0] IMPLICIT SEQUENCE { 85 thisMech MechType 86 -- MechType is OBJECT IDENTIFIER 87 -- representing "Kerberos V5" 88 innerContextToken ANY DEFINED BY thisMech 89 -- contents mechanism-specific; 90 -- ASN.1 usage within innerContextToken 91 -- is not required 92 } 93 94 The innerContextToken of the initial context token will consist of a 95 Kerberos V5 KRB_AP_REQ message, preceded by a two-byte token-id 96 (TOK_ID) field, which shall contain the value 01 00. 97 98 The above GSS-API framing shall be applied to all tokens emitted by 99 the Kerberos V5 GSS-API mechanism, including KRB_AP_REP, KRB_ERROR, 100 context-deletion, and per-message tokens, not just to the initial 101 token in a context establishment sequence. While not required by 102 RFC-1508, this enables implementations to perform enhanced error- 103 checking. The innerContextToken field of context establishment tokens 104 for the Kerberos V5 GSS-API mechanism will contain a Kerberos message 105 (KRB_AP_REQ, KRB_AP_REP or KRB_ERROR), preceded by a 2-byte TOK_ID 106 field containing 01 00 for KRB_AP_REQ messages, 02 00 for KRB_AP_REP 107 messages and 03 00 for KRB_ERROR messages. 108 109 110 111 112 113 114Linn Standards Track [Page 2] 115 116RFC 1964 Kerberos Version 5 GSS-API June 1996 117 118 1191.1.1. Initial Token 120 121 Relevant KRB_AP_REQ syntax (from RFC-1510) is as follows: 122 123 AP-REQ ::= [APPLICATION 14] SEQUENCE { 124 pvno [0] INTEGER, -- indicates Version 5 125 msg-type [1] INTEGER, -- indicates KRB_AP_REQ 126 ap-options[2] APOptions, 127 ticket[3] Ticket, 128 authenticator[4] EncryptedData 129 } 130 131 APOptions ::= BIT STRING { 132 reserved (0), 133 use-session-key (1), 134 mutual-required (2) 135 } 136 137 Ticket ::= [APPLICATION 1] SEQUENCE { 138 tkt-vno [0] INTEGER, -- indicates Version 5 139 realm [1] Realm, 140 sname [2] PrincipalName, 141 enc-part [3] EncryptedData 142 } 143 144 -- Encrypted part of ticket 145 EncTicketPart ::= [APPLICATION 3] SEQUENCE { 146 flags[0] TicketFlags, 147 key[1] EncryptionKey, 148 crealm[2] Realm, 149 cname[3] PrincipalName, 150 transited[4] TransitedEncoding, 151 authtime[5] KerberosTime, 152 starttime[6] KerberosTime OPTIONAL, 153 endtime[7] KerberosTime, 154 renew-till[8] KerberosTime OPTIONAL, 155 caddr[9] HostAddresses OPTIONAL, 156 authorization-data[10] AuthorizationData OPTIONAL 157 } 158 159 -- Unencrypted authenticator 160 Authenticator ::= [APPLICATION 2] SEQUENCE { 161 authenticator-vno[0] INTEGER, 162 crealm[1] Realm, 163 cname[2] PrincipalName, 164 cksum[3] Checksum OPTIONAL, 165 cusec[4] INTEGER, 166 ctime[5] KerberosTime, 167 168 169 170Linn Standards Track [Page 3] 171 172RFC 1964 Kerberos Version 5 GSS-API June 1996 173 174 175 subkey[6] EncryptionKey OPTIONAL, 176 seq-number[7] INTEGER OPTIONAL, 177 authorization-data[8] AuthorizationData OPTIONAL 178 } 179 180 For purposes of this specification, the authenticator shall include 181 the optional sequence number, and the checksum field shall be used to 182 convey channel binding, service flags, and optional delegation 183 information. The checksum will have a type of 0x8003 (a value being 184 registered within the Kerberos protocol specification), and a value 185 field of at least 24 bytes in length. The length of the value field 186 is extended beyond 24 bytes if and only if an optional facility to 187 carry a Kerberos-defined KRB_CRED message for delegation purposes is 188 supported by an implementation and active on a context. When 189 delegation is active, a TGT with its FORWARDABLE flag set will be 190 transferred within the KRB_CRED message. 191 192 The checksum value field's format is as follows: 193 194 Byte Name Description 195 0..3 Lgth Number of bytes in Bnd field; 196 Currently contains hex 10 00 00 00 197 (16, represented in little-endian form) 198 4..19 Bnd MD5 hash of channel bindings, taken over all non-null 199 components of bindings, in order of declaration. 200 Integer fields within channel bindings are represented 201 in little-endian order for the purposes of the MD5 202 calculation. 203 20..23 Flags Bit vector of context-establishment flags, 204 with values consistent with RFC-1509, p. 41: 205 GSS_C_DELEG_FLAG: 1 206 GSS_C_MUTUAL_FLAG: 2 207 GSS_C_REPLAY_FLAG: 4 208 GSS_C_SEQUENCE_FLAG: 8 209 GSS_C_CONF_FLAG: 16 210 GSS_C_INTEG_FLAG: 32 211 The resulting bit vector is encoded into bytes 20..23 212 in little-endian form. 213 24..25 DlgOpt The Delegation Option identifier (=1) [optional] 214 26..27 Dlgth The length of the Deleg field. [optional] 215 28..n Deleg A KRB_CRED message (n = Dlgth + 29) [optional] 216 217 In computing the contents of the "Bnd" field, the following detailed 218 points apply: 219 220 (1) Each integer field shall be formatted into four bytes, using 221 little-endian byte ordering, for purposes of MD5 hash 222 computation. 223 224 225 226Linn Standards Track [Page 4] 227 228RFC 1964 Kerberos Version 5 GSS-API June 1996 229 230 231 (2) All input length fields within gss_buffer_desc elements of a 232 gss_channel_bindings_struct, even those which are zero-valued, 233 shall be included in the hash calculation; the value elements of 234 gss_buffer_desc elements shall be dereferenced, and the 235 resulting data shall be included within the hash computation, 236 only for the case of gss_buffer_desc elements having non-zero 237 length specifiers. 238 239 (3) If the caller passes the value GSS_C_NO_BINDINGS instead of 240 a valid channel bindings structure, the Bnd field shall be set 241 to 16 zero-valued bytes. 242 243 In the initial Kerberos V5 GSS-API mechanism token (KRB_AP_REQ token) 244 from initiator to target, the GSS_C_DELEG_FLAG, GSS_C_MUTUAL_FLAG, 245 GSS_C_REPLAY_FLAG, and GSS_C_SEQUENCE_FLAG values shall each be set 246 as the logical AND of the initiator's corresponding request flag to 247 GSS_Init_sec_context() and a Boolean indicator of whether that 248 optional service is available to GSS_Init_sec_context()'s caller. 249 GSS_C_CONF_FLAG and GSS_C_INTEG_FLAG, for which no corresponding 250 context-level input indicator flags to GSS_Init_sec_context() exist, 251 shall each be set to indicate whether their respective per-message 252 protection services are available for use on the context being 253 established. 254 255 When input source address channel binding values are provided by a 256 caller (i.e., unless the input argument is GSS_C_NO_BINDINGS or the 257 source address specifier value within the input structure is 258 GSS_C_NULL_ADDRTYPE), and the corresponding token received from the 259 context's peer bears address restrictions, it is recommended that an 260 implementation of the Kerberos V5 GSS-API mechanism should check that 261 the source address as provided by the caller matches that in the 262 received token, and should return the GSS_S_BAD_BINDINGS major_status 263 value if a mismatch is detected. Note: discussion is ongoing about 264 the strength of recommendation to be made in this area, and on the 265 circumstances under which such a recommendation should be applicable; 266 implementors are therefore advised that changes on this matter may be 267 included in subsequent versions of this specification. 268 2691.1.2. Response Tokens 270 271 A context establishment sequence based on the Kerberos V5 mechanism 272 will perform one-way authentication (without confirmation or any 273 return token from target to initiator in response to the initiator's 274 KRB_AP_REQ) if the mutual_req bit is not set in the application's 275 call to GSS_Init_sec_context(). Applications requiring confirmation 276 that their authentication was successful should request mutual 277 authentication, resulting in a "mutual-required" indication within 278 KRB_AP_REQ APoptions and the setting of the mutual_req bit in the 279 280 281 282Linn Standards Track [Page 5] 283 284RFC 1964 Kerberos Version 5 GSS-API June 1996 285 286 287 flags field of the authenticator checksum. In response to such a 288 request, the context target will reply to the initiator with a token 289 containing either a KRB_AP_REP or KRB_ERROR, completing the mutual 290 context establishment exchange. 291 292 Relevant KRB_AP_REP syntax is as follows: 293 294 AP-REP ::= [APPLICATION 15] SEQUENCE { 295 pvno [0] INTEGER, -- represents Kerberos V5 296 msg-type [1] INTEGER, -- represents KRB_AP_REP 297 enc-part [2] EncryptedData 298 } 299 300 EncAPRepPart ::= [APPLICATION 27] SEQUENCE { 301 ctime [0] KerberosTime, 302 cusec [1] INTEGER, 303 subkey [2] EncryptionKey OPTIONAL, 304 seq-number [3] INTEGER OPTIONAL 305 } 306 307 The optional seq-number element within the AP-REP's EncAPRepPart 308 shall be included. 309 310 The syntax of KRB_ERROR is as follows: 311 312 KRB-ERROR ::= [APPLICATION 30] SEQUENCE { 313 pvno[0] INTEGER, 314 msg-type[1] INTEGER, 315 ctime[2] KerberosTime OPTIONAL, 316 cusec[3] INTEGER OPTIONAL, 317 stime[4] KerberosTime, 318 susec[5] INTEGER, 319 error-code[6] INTEGER, 320 crealm[7] Realm OPTIONAL, 321 cname[8] PrincipalName OPTIONAL, 322 realm[9] Realm, -- Correct realm 323 sname[10] PrincipalName, -- Correct name 324 e-text[11] GeneralString OPTIONAL, 325 e-data[12] OCTET STRING OPTIONAL 326 } 327 328 Values to be transferred in the error-code field of a KRB-ERROR 329 message are defined in [RFC-1510], not in this specification. 330 331 332 333 334 335 336 337 338Linn Standards Track [Page 6] 339 340RFC 1964 Kerberos Version 5 GSS-API June 1996 341 342 3431.2. Per-Message and Context Deletion Tokens 344 345 Three classes of tokens are defined in this section: "MIC" tokens, 346 emitted by calls to GSS_GetMIC() (formerly GSS_Sign()) and consumed 347 by calls to GSS_VerifyMIC() (formerly GSS_Verify()), "Wrap" tokens, 348 emitted by calls to GSS_Wrap() (formerly GSS_Seal()) and consumed by 349 calls to GSS_Unwrap() (formerly GSS_Unseal()), and context deletion 350 tokens, emitted by calls to GSS_Delete_sec_context() and consumed by 351 calls to GSS_Process_context_token(). Note: References to GSS-API 352 per-message routines in the remainder of this specification will be 353 based on those routines' newer recommended names rather than those 354 names' predecessors. 355 356 Several variants of cryptographic keys are used in generation and 357 processing of per-message tokens: 358 359 (1) context key: uses Kerberos session key (or subkey, if 360 present in authenticator emitted by context initiator) directly 361 362 (2) confidentiality key: forms variant of context key by 363 exclusive-OR with the hexadecimal constant f0f0f0f0f0f0f0f0. 364 365 (3) MD2.5 seed key: forms variant of context key by reversing 366 the bytes of the context key (i.e. if the original key is the 367 8-byte sequence {aa, bb, cc, dd, ee, ff, gg, hh}, the seed key 368 will be {hh, gg, ff, ee, dd, cc, bb, aa}). 369 3701.2.1. Per-message Tokens - MIC 371 372Use of the GSS_GetMIC() call yields a token, separate from the user 373data being protected, which can be used to verify the integrity of 374that data as received. The token has the following format: 375 376 Byte no Name Description 377 0..1 TOK_ID Identification field. 378 Tokens emitted by GSS_GetMIC() contain 379 the hex value 01 01 in this field. 380 2..3 SGN_ALG Integrity algorithm indicator. 381 00 00 - DES MAC MD5 382 01 00 - MD2.5 383 02 00 - DES MAC 384 4..7 Filler Contains ff ff ff ff 385 8..15 SND_SEQ Sequence number field. 386 16..23 SGN_CKSUM Checksum of "to-be-signed data", 387 calculated according to algorithm 388 specified in SGN_ALG field. 389 390 391 392 393 394Linn Standards Track [Page 7] 395 396RFC 1964 Kerberos Version 5 GSS-API June 1996 397 398 399 GSS-API tokens must be encapsulated within the higher-level protocol 400 by the application; no embedded length field is necessary. 401 4021.2.1.1. Checksum 403 404 Checksum calculation procedure (common to all algorithms): Checksums 405 are calculated over the data field, logically prepended by the first 406 8 bytes of the plaintext packet header. The resulting value binds 407 the data to the packet type and signature algorithm identifier 408 fields. 409 410 DES MAC MD5 algorithm: The checksum is formed by computing an MD5 411 [RFC-1321] hash over the plaintext data, and then computing a DES-CBC 412 MAC on the 16-byte MD5 result. A standard 64-bit DES-CBC MAC is 413 computed per [FIPS-PUB-113], employing the context key and a zero IV. 414 The 8-byte result is stored in the SGN_CKSUM field. 415 416 MD2.5 algorithm: The checksum is formed by first DES-CBC encrypting a 417 16-byte zero-block, using a zero IV and a key formed by reversing the 418 bytes of the context key (i.e. if the original key is the 8-byte 419 sequence {aa, bb, cc, dd, ee, ff, gg, hh}, the checksum key will be 420 {hh, gg, ff, ee, dd, cc, bb, aa}). The resulting 16-byte value is 421 logically prepended to the to-be-signed data. A standard MD5 422 checksum is calculated over the combined data, and the first 8 bytes 423 of the result are stored in the SGN_CKSUM field. Note 1: we refer to 424 this algorithm informally as "MD2.5" to connote the fact that it uses 425 half of the 128 bits generated by MD5; use of only a subset of the 426 MD5 bits is intended to protect against the prospect that data could 427 be postfixed to an existing message with corresponding modifications 428 being made to the checksum. Note 2: This algorithm is fairly novel 429 and has received more limited evaluation than that to which other 430 integrity algorithms have been subjected. An initial, limited 431 evaluation indicates that it may be significantly weaker than DES MAC 432 MD5. 433 434 DES-MAC algorithm: A standard 64-bit DES-CBC MAC is computed on the 435 plaintext data per [FIPS-PUB-113], employing the context key and a 436 zero IV. Padding procedures to accomodate plaintext data lengths 437 which may not be integral multiples of 8 bytes are defined in [FIPS- 438 PUB-113]. The result is an 8-byte value, which is stored in the 439 SGN_CKSUM field. Support for this algorithm may not be present in 440 all implementations. 441 4421.2.1.2. Sequence Number 443 444 Sequence number field: The 8 byte plaintext sequence number field is 445 formed from the sender's four-byte sequence number as follows. If 446 the four bytes of the sender's sequence number are named s0, s1, s2 447 448 449 450Linn Standards Track [Page 8] 451 452RFC 1964 Kerberos Version 5 GSS-API June 1996 453 454 455 and s3 (from least to most significant), the plaintext sequence 456 number field is the 8 byte sequence: (s0, s1, s2, s3, di, di, di, 457 di), where 'di' is the direction-indicator (Hex 0 - sender is the 458 context initiator, Hex FF - sender is the context acceptor). The 459 field is then DES-CBC encrypted using the context key and an IV 460 formed from the first 8 bytes of the previously calculated SGN_CKSUM 461 field. After sending a GSS_GetMIC() or GSS_Wrap() token, the sender's 462 sequence number is incremented by one. 463 464 The receiver of the token will first verify the SGN_CKSUM field. If 465 valid, the sequence number field may be decrypted and compared to the 466 expected sequence number. The repetition of the (effectively 1-bit) 467 direction indicator within the sequence number field provides 468 redundancy so that the receiver may verify that the decryption 469 succeeded. 470 471 Since the checksum computation is used as an IV to the sequence 472 number decryption, attempts to splice a checksum and sequence number 473 from different messages will be detected. The direction indicator 474 will detect packets that have been maliciously reflected. 475 476 The sequence number provides a basis for detection of replayed 477 tokens. Replay detection can be performed using state information 478 retained on received sequence numbers, interpreted in conjunction 479 with the security context on which they arrive. 480 481 Provision of per-message replay and out-of-sequence detection 482 services is optional for implementations of the Kerberos V5 GSS-API 483 mechanism. Further, it is recommended that implementations of the 484 Kerberos V5 GSS-API mechanism which offer these services should honor 485 a caller's request that the services be disabled on a context. 486 Specifically, if replay_det_req_flag is input FALSE, replay_det_state 487 should be returned FALSE and the GSS_DUPLICATE_TOKEN and 488 GSS_OLD_TOKEN stati should not be indicated as a result of duplicate 489 detection when tokens are processed; if sequence_req_flag is input 490 FALSE, sequence_state should be returned FALSE and 491 GSS_DUPLICATE_TOKEN, GSS_OLD_TOKEN, and GSS_UNSEQ_TOKEN stati should 492 not be indicated as a result of out-of-sequence detection when tokens 493 are processed. 494 4951.2.2. Per-message Tokens - Wrap 496 497 Use of the GSS_Wrap() call yields a token which encapsulates the 498 input user data (optionally encrypted) along with associated 499 integrity check quantities. The token emitted by GSS_Wrap() consists 500 of an integrity header whose format is identical to that emitted by 501 GSS_GetMIC() (except that the TOK_ID field contains the value 02 01), 502 followed by a body portion that contains either the plaintext data 503 504 505 506Linn Standards Track [Page 9] 507 508RFC 1964 Kerberos Version 5 GSS-API June 1996 509 510 511 (if SEAL_ALG = ff ff) or encrypted data for any other supported value 512 of SEAL_ALG. Currently, only SEAL_ALG = 00 00 is supported, and 513 means that DES-CBC encryption is being used to protect the data. 514 515 The GSS_Wrap() token has the following format: 516 517 Byte no Name Description 518 0..1 TOK_ID Identification field. 519 Tokens emitted by GSS_Wrap() contain 520 the hex value 02 01 in this field. 521 2..3 SGN_ALG Checksum algorithm indicator. 522 00 00 - DES MAC MD5 523 01 00 - MD2.5 524 02 00 - DES MAC 525 4..5 SEAL_ALG ff ff - none 526 00 00 - DES 527 6..7 Filler Contains ff ff 528 8..15 SND_SEQ Encrypted sequence number field. 529 16..23 SGN_CKSUM Checksum of plaintext padded data, 530 calculated according to algorithm 531 specified in SGN_ALG field. 532 24..last Data encrypted or plaintext padded data 533 534 GSS-API tokens must be encapsulated within the higher-level protocol 535 by the application; no embedded length field is necessary. 536 5371.2.2.1. Checksum 538 539 Checksum calculation procedure (common to all algorithms): Checksums 540 are calculated over the plaintext padded data field, logically 541 prepended by the first 8 bytes of the plaintext packet header. The 542 resulting signature binds the data to the packet type, protocol 543 version, and signature algorithm identifier fields. 544 545 DES MAC MD5 algorithm: The checksum is formed by computing an MD5 546 hash over the plaintext padded data, and then computing a DES-CBC MAC 547 on the 16-byte MD5 result. A standard 64-bit DES-CBC MAC is computed 548 per [FIPS-PUB-113], employing the context key and a zero IV. The 8- 549 byte result is stored in the SGN_CKSUM field. 550 551 MD2.5 algorithm: The checksum is formed by first DES-CBC encrypting a 552 16-byte zero-block, using a zero IV and a key formed by reversing the 553 bytes of the context key (i.e., if the original key is the 8-byte 554 sequence {aa, bb, cc, dd, ee, ff, gg, hh}, the checksum key will be 555 {hh, gg, ff, ee, dd, cc, bb, aa}). The resulting 16-byte value is 556 logically pre-pended to the "to-be-signed data". A standard MD5 557 checksum is calculated over the combined data, and the first 8 bytes 558 of the result are stored in the SGN_CKSUM field. 559 560 561 562Linn Standards Track [Page 10] 563 564RFC 1964 Kerberos Version 5 GSS-API June 1996 565 566 567 DES-MAC algorithm: A standard 64-bit DES-CBC MAC is computed on the 568 plaintext padded data per [FIPS-PUB-113], employing the context key 569 and a zero IV. The plaintext padded data is already assured to be an 570 integral multiple of 8 bytes; no additional padding is required or 571 applied in order to accomplish MAC calculation. The result is an 8- 572 byte value, which is stored in the SGN_CKSUM field. Support for this 573 lgorithm may not be present in all implementations. 574 5751.2.2.2. Sequence Number 576 577 Sequence number field: The 8 byte plaintext sequence number field is 578 formed from the sender's four-byte sequence number as follows. If 579 the four bytes of the sender's sequence number are named s0, s1, s2 580 and s3 (from least to most significant), the plaintext sequence 581 number field is the 8 byte sequence: (s0, s1, s2, s3, di, di, di, 582 di), where 'di' is the direction-indicator (Hex 0 - sender is the 583 context initiator, Hex FF - sender is the context acceptor). 584 585 The field is then DES-CBC encrypted using the context key and an IV 586 formed from the first 8 bytes of the SEAL_CKSUM field. 587 588 After sending a GSS_GetMIC() or GSS_Wrap() token, the sender's 589 sequence numbers are incremented by one. 590 5911.2.2.3. Padding 592 593 Data padding: Before encryption and/or signature calculation, 594 plaintext data is padded to the next highest multiple of 8 bytes, by 595 appending between 1 and 8 bytes, the value of each such byte being 596 the total number of pad bytes. For example, given data of length 20 597 bytes, four pad bytes will be appended, and each byte will contain 598 the hex value 04. An 8-byte random confounder is prepended to the 599 data, and signatures are calculated over the resulting padded 600 plaintext. 601 602 After padding, the data is encrypted according to the algorithm 603 specified in the SEAL_ALG field. For SEAL_ALG=DES (the only non-null 604 algorithm currently supported), the data is encrypted using DES-CBC, 605 with an IV of zero. The key used is derived from the established 606 context key by XOR-ing the context key with the hexadecimal constant 607 f0f0f0f0f0f0f0f0. 608 6091.2.3. Context deletion token 610 611 The token emitted by GSS_Delete_sec_context() is based on the packet 612 format for tokens emitted by GSS_GetMIC(). The context-deletion 613 token has the following format: 614 615 616 617 618Linn Standards Track [Page 11] 619 620RFC 1964 Kerberos Version 5 GSS-API June 1996 621 622 623 Byte no Name Description 624 0..1 TOK_ID Identification field. 625 Tokens emitted by 626 GSS_Delete_sec_context() contain 627 the hex value 01 02 in this field. 628 2..3 SGN_ALG Integrity algorithm indicator. 629 00 00 - DES MAC MD5 630 01 00 - MD2.5 631 02 00 - DES MAC 632 4..7 Filler Contains ff ff ff ff 633 8..15 SND_SEQ Sequence number field. 634 16..23 SGN_CKSUM Checksum of "to-be-signed data", 635 calculated according to algorithm 636 specified in SGN_ALG field. 637 638 SGN_ALG and SND_SEQ will be calculated as for tokens emitted by 639 GSS_GetMIC(). The SGN_CKSUM will be calculated as for tokens emitted 640 by GSS_GetMIC(), except that the user-data component of the "to-be- 641 signed" data will be a zero-length string. 642 6432. Name Types and Object Identifiers 644 645 This section discusses the name types which may be passed as input to 646 the Kerberos V5 GSS-API mechanism's GSS_Import_name() call, and their 647 associated identifier values. It defines interface elements in 648 support of portability, and assumes use of C language bindings per 649 RFC-1509. In addition to specifying OID values for name type 650 identifiers, symbolic names are included and recommended to GSS-API 651 implementors in the interests of convenience to callers. It is 652 understood that not all implementations of the Kerberos V5 GSS-API 653 mechanism need support all name types in this list, and that 654 additional name forms will likely be added to this list over time. 655 Further, the definitions of some or all name types may later migrate 656 to other, mechanism-independent, specifications. The occurrence of a 657 name type in this specification is specifically not intended to 658 suggest that the type may be supported only by an implementation of 659 the Kerberos V5 mechanism. In particular, the occurrence of the 660 string "_KRB5_" in the symbolic name strings constitutes a means to 661 unambiguously register the name strings, avoiding collision with 662 other documents; it is not meant to limit the name types' usage or 663 applicability. 664 665 For purposes of clarification to GSS-API implementors, this section's 666 discussion of some name forms describes means through which those 667 forms can be supported with existing Kerberos technology. These 668 discussions are not intended to preclude alternative implementation 669 strategies for support of the name forms within Kerberos mechanisms 670 or mechanisms based on other technologies. To enhance application 671 672 673 674Linn Standards Track [Page 12] 675 676RFC 1964 Kerberos Version 5 GSS-API June 1996 677 678 679 portability, implementors of mechanisms are encouraged to support 680 name forms as defined in this section, even if their mechanisms are 681 independent of Kerberos V5. 682 6832.1. Mandatory Name Forms 684 685 This section discusses name forms which are to be supported by all 686 conformant implementations of the Kerberos V5 GSS-API mechanism. 687 6882.1.1. Kerberos Principal Name Form 689 690 This name form shall be represented by the Object Identifier {iso(1) 691 member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) 692 krb5(2) krb5_name(1)}. The recommended symbolic name for this type 693 is "GSS_KRB5_NT_PRINCIPAL_NAME". 694 695 This name type corresponds to the single-string representation of a 696 Kerberos name. (Within the MIT Kerberos V5 implementation, such 697 names are parseable with the krb5_parse_name() function.) The 698 elements included within this name representation are as follows, 699 proceeding from the beginning of the string: 700 701 (1) One or more principal name components; if more than one 702 principal name component is included, the components are 703 separated by `/`. Arbitrary octets may be included within 704 principal name components, with the following constraints and 705 special considerations: 706 707 (1a) Any occurrence of the characters `@` or `/` within a 708 name component must be immediately preceded by the `\` 709 quoting character, to prevent interpretation as a component 710 or realm separator. 711 712 (1b) The ASCII newline, tab, backspace, and null characters 713 may occur directly within the component or may be 714 represented, respectively, by `\n`, `\t`, `\b`, or `\0`. 715 716 (1c) If the `\` quoting character occurs outside the contexts 717 described in (1a) and (1b) above, the following character is 718 interpreted literally. As a special case, this allows the 719 doubled representation `\\` to represent a single occurrence 720 of the quoting character. 721 722 (1d) An occurrence of the `\` quoting character as the last 723 character of a component is illegal. 724 725 726 727 728 729 730Linn Standards Track [Page 13] 731 732RFC 1964 Kerberos Version 5 GSS-API June 1996 733 734 735 (2) Optionally, a `@` character, signifying that a realm name 736 immediately follows. If no realm name element is included, the 737 local realm name is assumed. The `/` , `:`, and null characters 738 may not occur within a realm name; the `@`, newline, tab, and 739 backspace characters may be included using the quoting 740 conventions described in (1a), (1b), and (1c) above. 741 7422.1.2. Host-Based Service Name Form 743 744 This name form has been incorporated at the mechanism-independent 745 GSS-API level as of GSS-API, Version 2. This subsection retains the 746 Object Identifier and symbolic name assignments previously made at 747 the Kerberos V5 GSS-API mechanism level, and adopts the definition as 748 promoted to the mechanism-independent level. 749 750 This name form shall be represented by the Object Identifier {iso(1) 751 member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) 752 generic(1) service_name(4)}. The previously recommended symbolic 753 name for this type is "GSS_KRB5_NT_HOSTBASED_SERVICE_NAME". The 754 currently preferred symbolic name for this type is 755 "GSS_C_NT_HOSTBASED_SERVICE". 756 757 This name type is used to represent services associated with host 758 computers. This name form is constructed using two elements, 759 "service" and "hostname", as follows: 760 761 service@hostname 762 763 When a reference to a name of this type is resolved, the "hostname" 764 is canonicalized by attempting a DNS lookup and using the fully- 765 qualified domain name which is returned, or by using the "hostname" 766 as provided if the DNS lookup fails. The canonicalization operation 767 also maps the host's name into lower-case characters. 768 769 The "hostname" element may be omitted. If no "@" separator is 770 included, the entire name is interpreted as the service specifier, 771 with the "hostname" defaulted to the canonicalized name of the local 772 host. 773 774 Values for the "service" element will be registered with the IANA. 775 7762.1.3. Exported Name Object Form for Kerberos V5 Mechanism 777 778 Support for this name form is not required for GSS-V1 779 implementations, but will be required for use in conjunction with the 780 GSS_Export_name() call planned for GSS-API Version 2. Use of this 781 name form will be signified by a "GSS-API Exported Name Object" OID 782 value which will be defined at the mechanism-independent level for 783 784 785 786Linn Standards Track [Page 14] 787 788RFC 1964 Kerberos Version 5 GSS-API June 1996 789 790 791 GSS-API Version 2. 792 793 This name type represents a self-describing object, whose framing 794 structure will be defined at the mechanism-independent level for 795 GSS-API Version 2. When generated by the Kerberos V5 mechanism, the 796 Mechanism OID within the exportable name shall be that of the 797 Kerberos V5 mechanism. The name component within the exportable name 798 shall be a contiguous string with structure as defined for the 799 Kerberos Principal Name Form. 800 801 In order to achieve a distinguished encoding for comparison purposes, 802 the following additional constraints are imposed on the export 803 operation: 804 805 (1) all occurrences of the characters `@`, `/`, and `\` within 806 principal components or realm names shall be quoted with an 807 immediately-preceding `\`. 808 809 (2) all occurrences of the null, backspace, tab, or newline 810 characters within principal components or realm names will be 811 represented, respectively, with `\0`, `\b`, `\t`, or `\n`. 812 813 (3) the `\` quoting character shall not be emitted within an 814 exported name except to accomodate cases (1) and (2). 815 8162.2. Optional Name Forms 817 818 This section discusses additional name forms which may optionally be 819 supported by implementations of the Kerberos V5 GSS-API mechanism. 820 It is recognized that some of the name forms cited here are derived 821 from UNIX(tm) operating system platforms; some listed forms may be 822 irrelevant to non-UNIX platforms, and definition of additional forms 823 corresponding to such platforms may also be appropriate. It is also 824 recognized that OS-specific functions outside GSS-API are likely to 825 exist in order to perform translations among these forms, and that 826 GSS-API implementations supporting these forms may themselves be 827 layered atop such OS-specific functions. Inclusion of this support 828 within GSS-API implementations is intended as a convenience to 829 applications. 830 8312.2.1. User Name Form 832 833 This name form shall be represented by the Object Identifier {iso(1) 834 member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) 835 generic(1) user_name(1)}. The recommended symbolic name for this 836 type is "GSS_KRB5_NT_USER_NAME". 837 838 This name type is used to indicate a named user on a local system. 839 840 841 842Linn Standards Track [Page 15] 843 844RFC 1964 Kerberos Version 5 GSS-API June 1996 845 846 847 Its interpretation is OS-specific. This name form is constructed as: 848 849 username 850 851 Assuming that users' principal names are the same as their local 852 operating system names, an implementation of GSS_Import_name() based 853 on Kerberos V5 technology can process names of this form by 854 postfixing an "@" sign and the name of the local realm. 855 8562.2.2. Machine UID Form 857 858 This name form shall be represented by the Object Identifier {iso(1) 859 member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) 860 generic(1) machine_uid_name(2)}. The recommended symbolic name for 861 this type is "GSS_KRB5_NT_MACHINE_UID_NAME". 862 863 This name type is used to indicate a numeric user identifier 864 corresponding to a user on a local system. Its interpretation is 865 OS-specific. The gss_buffer_desc representing a name of this type 866 should contain a locally-significant uid_t, represented in host byte 867 order. The GSS_Import_name() operation resolves this uid into a 868 username, which is then treated as the User Name Form. 869 8702.2.3. String UID Form 871 872 This name form shall be represented by the Object Identifier {iso(1) 873 member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) 874 generic(1) string_uid_name(3)}. The recommended symbolic name for 875 this type is "GSS_KRB5_NT_STRING_UID_NAME". 876 877 This name type is used to indicate a string of digits representing 878 the numeric user identifier of a user on a local system. Its 879 interpretation is OS-specific. This name type is similar to the 880 Machine UID Form, except that the buffer contains a string 881 representing the uid_t. 882 8833. Credentials Management 884 885 The Kerberos V5 protocol uses different credentials (in the GSSAPI 886 sense) for initiating and accepting security contexts. Normal 887 clients receive a ticket-granting ticket (TGT) and an associated 888 session key at "login" time; the pair of a TGT and its corresponding 889 session key forms a credential which is suitable for initiating 890 security contexts. A ticket-granting ticket, its session key, and 891 any other (ticket, key) pairs obtained through use of the ticket- 892 granting-ticket, are typically stored in a Kerberos V5 credentials 893 cache, sometimes known as a ticket file. 894 895 896 897 898Linn Standards Track [Page 16] 899 900RFC 1964 Kerberos Version 5 GSS-API June 1996 901 902 903 The encryption key used by the Kerberos server to seal tickets for a 904 particular application service forms the credentials suitable for 905 accepting security contexts. These service keys are typically stored 906 in a Kerberos V5 key table, or srvtab file. In addition to their use 907 as accepting credentials, these service keys may also be used to 908 obtain initiating credentials for their service principal. 909 910 The Kerberos V5 mechanism's credential handle may contain references 911 to either or both types of credentials. It is a local matter how the 912 Kerberos V5 mechanism implementation finds the appropriate Kerberos 913 V5 credentials cache or key table. 914 915 However, when the Kerberos V5 mechanism attempts to obtain initiating 916 credentials for a service principal which are not available in a 917 credentials cache, and the key for that service principal is 918 available in a Kerberos V5 key table, the mechanism should use the 919 service key to obtain initiating credentials for that service. This 920 should be accomplished by requesting a ticket-granting-ticket from 921 the Kerberos Key Distribution Center (KDC), and decrypting the KDC's 922 reply using the service key. 923 9244. Parameter Definitions 925 926 This section defines parameter values used by the Kerberos V5 GSS-API 927 mechanism. It defines interface elements in support of portability, 928 and assumes use of C language bindings per RFC-1509. 929 9304.1. Minor Status Codes 931 932 This section recommends common symbolic names for minor_status values 933 to be returned by the Kerberos V5 GSS-API mechanism. Use of these 934 definitions will enable independent implementors to enhance 935 application portability across different implementations of the 936 mechanism defined in this specification. (In all cases, 937 implementations of GSS_Display_status() will enable callers to 938 convert minor_status indicators to text representations.) Each 939 implementation should make available, through include files or other 940 means, a facility to translate these symbolic names into the concrete 941 values which a particular GSS-API implementation uses to represent 942 the minor_status values specified in this section. 943 944 It is recognized that this list may grow over time, and that the need 945 for additional minor_status codes specific to particular 946 implementations may arise. It is recommended, however, that 947 implementations should return a minor_status value as defined on a 948 mechanism-wide basis within this section when that code is accurately 949 representative of reportable status rather than using a separate, 950 implementation-defined code. 951 952 953 954Linn Standards Track [Page 17] 955 956RFC 1964 Kerberos Version 5 GSS-API June 1996 957 958 9594.1.1. Non-Kerberos-specific codes 960 961 GSS_KRB5_S_G_BAD_SERVICE_NAME 962 /* "No @ in SERVICE-NAME name string" */ 963 GSS_KRB5_S_G_BAD_STRING_UID 964 /* "STRING-UID-NAME contains nondigits" */ 965 GSS_KRB5_S_G_NOUSER 966 /* "UID does not resolve to username" */ 967 GSS_KRB5_S_G_VALIDATE_FAILED 968 /* "Validation error" */ 969 GSS_KRB5_S_G_BUFFER_ALLOC 970 /* "Couldn't allocate gss_buffer_t data" */ 971 GSS_KRB5_S_G_BAD_MSG_CTX 972 /* "Message context invalid" */ 973 GSS_KRB5_S_G_WRONG_SIZE 974 /* "Buffer is the wrong size" */ 975 GSS_KRB5_S_G_BAD_USAGE 976 /* "Credential usage type is unknown" */ 977 GSS_KRB5_S_G_UNKNOWN_QOP 978 /* "Unknown quality of protection specified" */ 979 9804.1.2. Kerberos-specific-codes 981 982 GSS_KRB5_S_KG_CCACHE_NOMATCH 983 /* "Principal in credential cache does not match desired name" */ 984 GSS_KRB5_S_KG_KEYTAB_NOMATCH 985 /* "No principal in keytab matches desired name" */ 986 GSS_KRB5_S_KG_TGT_MISSING 987 /* "Credential cache has no TGT" */ 988 GSS_KRB5_S_KG_NO_SUBKEY 989 /* "Authenticator has no subkey" */ 990 GSS_KRB5_S_KG_CONTEXT_ESTABLISHED 991 /* "Context is already fully established" */ 992 GSS_KRB5_S_KG_BAD_SIGN_TYPE 993 /* "Unknown signature type in token" */ 994 GSS_KRB5_S_KG_BAD_LENGTH 995 /* "Invalid field length in token" */ 996 GSS_KRB5_S_KG_CTX_INCOMPLETE 997 /* "Attempt to use incomplete security context" */ 998 9994.2. Quality of Protection Values 1000 1001 This section defines Quality of Protection (QOP) values to be used 1002 with the Kerberos V5 GSS-API mechanism as input to GSS_Wrap() and 1003 GSS_GetMIC() routines in order to select among alternate integrity 1004 and confidentiality algorithms. Additional QOP values may be added in 1005 future versions of this specification. Non-overlapping bit positions 1006 are and will be employed in order that both integrity and 1007 1008 1009 1010Linn Standards Track [Page 18] 1011 1012RFC 1964 Kerberos Version 5 GSS-API June 1996 1013 1014 1015 confidentiality QOP may be selected within a single parameter, via 1016 inclusive-OR of the specified integrity and confidentiality values. 1017 10184.2.1. Integrity Algorithms 1019 1020 The following Quality of Protection (QOP) values are currently 1021 defined for the Kerberos V5 GSS-API mechanism, and are used to select 1022 among alternate integrity checking algorithms. 1023 1024 GSS_KRB5_INTEG_C_QOP_MD5 (numeric value: 1) 1025 /* Integrity using partial MD5 ("MD2.5") of plaintext */ 1026 1027 GSS_KRB5_INTEG_C_QOP_DES_MD5 (numeric value: 2) 1028 /* Integrity using DES MAC of MD5 of plaintext */ 1029 1030 GSS_KRB5_INTEG_C_QOP_DES_MAC (numeric value: 3) 1031 /* Integrity using DES MAC of plaintext */ 1032 10334.2.2. Confidentiality Algorithms 1034 1035 Only one confidentiality QOP value is currently defined for the 1036 Kerberos V5 GSS-API mechanism: 1037 1038 GSS_KRB5_CONF_C_QOP_DES (numeric value: 0) 1039 /* Confidentiality with DES */ 1040 1041 Note: confidentiality QOP should be indicated only by GSS-API calls 1042 capable of providing confidentiality services. If non-zero 1043 confidentiality QOP values are defined in future to represent 1044 different algorithms, therefore, the bit positions containing those 1045 values should be cleared before being returned by implementations of 1046 GSS_GetMIC() and GSS_VerifyMIC(). 1047 10484.3. Buffer Sizes 1049 1050 All implementations of this specification shall be capable of 1051 accepting buffers of at least 16 Kbytes as input to GSS_GetMIC(), 1052 GSS_VerifyMIC(), and GSS_Wrap(), and shall be capable of accepting 1053 the output_token generated by GSS_Wrap() for a 16 Kbyte input buffer 1054 as input to GSS_Unwrap(). Support for larger buffer sizes is optional 1055 but recommended. 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066Linn Standards Track [Page 19] 1067 1068RFC 1964 Kerberos Version 5 GSS-API June 1996 1069 1070 10715. Security Considerations 1072 1073 Security issues are discussed throughout this memo. 1074 10756. References 1076 1077 1078 [RFC-1321]: Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1079 1321, April 1992. 1080 1081 [RFC-1508]: Linn, J., "Generic Security Service Application Program 1082 Interface", RFC 1508, September 1993. 1083 1084 [RFC-1509]: Wray, J., "Generic Security Service Application Program 1085 Interface: C-bindings", RFC 1509, September 1993. 1086 1087 [RFC-1510]: Kohl, J., and C. Neuman, "The Kerberos Network 1088 Authentication Service (V5)", RFC 1510, September 1993. 1089 1090 [FIPS-PUB-113]: National Bureau of Standards, Federal Information 1091 Processing Standard 113, "Computer Data Authentication", May 1985. 1092 1093AUTHOR'S ADDRESS 1094 1095 John Linn 1096 OpenVision Technologies 1097 One Main St. 1098 Cambridge, MA 02142 USA 1099 1100 Phone: +1 617.374.2245 1101 EMail: John.Linn@ov.com 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122Linn Standards Track [Page 20] 1123 1124