1 2INTERNET-DRAFT Tom Yu 3Common Authentication Technology WG MIT 4draft-ietf-cat-krb5gss-mech2-03.txt 04 March 2000 5 6 The Kerberos Version 5 GSSAPI Mechanism, Version 2 7 8Status of This Memo 9 10 This document is an Internet-Draft and is in full conformance with 11 all provisions of Section 10 of RFC2026. 12 13 Internet-Drafts are working documents of the Internet Engineering 14 Task Force (IETF), its areas, and its working groups. Note that 15 other groups may also distribute working documents as Internet- 16 Drafts. 17 18 Internet-Drafts are draft documents valid for a maximum of six months 19 and may be updated, replaced, or obsoleted by other documents at any 20 time. It is inappropriate to use Internet-Drafts as reference 21 material or to cite them other than as "work in progress." 22 23 The list of current Internet-Drafts can be accessed at 24 http://www.ietf.org/ietf/1id-abstracts.txt 25 26 The list of Internet-Draft Shadow Directories can be accessed at 27 http://www.ietf.org/shadow.html. 28 29 Comments on this document should be sent to 30 "ietf-cat-wg@lists.stanford.edu", the IETF Common Authentication 31 Technology WG discussion list. 32 33Abstract 34 35 This document defines protocols, procedures, and conventions to be 36 employed by peers implementing the Generic Security Service 37 Application Program Interface (as specified in RFC 2743) when using 38 Kerberos Version 5 technology (as specified in RFC 1510). This 39 obsoletes RFC 1964. 40 41Acknowledgements 42 43 Much of the material in this specification is based on work done for 44 Cygnus Solutions by Marc Horowitz. 45 46Table of Contents 47 48 Status of This Memo ............................................ 1 49 Abstract ....................................................... 1 50 Acknowledgements ............................................... 1 51 Table of Contents .............................................. 1 52 1. Introduction ............................................... 3 53 2. Token Formats .............................................. 3 54 2.1. Packet Notation ....................................... 3 55 56Yu Document Expiration: 04 Sep 2000 [Page 1] 57 58Internet-Draft krb5-gss-mech2-03 March 2000 59 60 2.2. Mechanism OID ......................................... 4 61 2.3. Context Establishment ................................. 4 62 2.3.1. Option Format .................................... 4 63 2.3.1.1. Delegated Credentials Option ................ 5 64 2.3.1.2. Null Option ................................. 5 65 2.3.2. Initial Token .................................... 6 66 2.3.2.1. Data to be Checksummed in APREQ ............. 8 67 2.3.3. Response Token ................................... 10 68 2.4. Per-message Tokens .................................... 12 69 2.4.1. Sequence Number Usage ............................ 12 70 2.4.2. MIC Token ........................................ 12 71 2.4.2.1. Data to be Checksummed in MIC Token ......... 13 72 2.4.3. Wrap Token ....................................... 14 73 2.4.3.1. Wrap Token With Integrity Only .............. 14 74 2.4.3.2. Wrap Token With Integrity and Encryption 75 ............................................. 15 76 2.4.3.2.1. Data to be Encrypted in Wrap Token ..... 16 77 3. ASN.1 Encoding of Octet Strings ............................ 17 78 4. Name Types ................................................. 18 79 4.1. Mandatory Name Forms .................................. 18 80 4.1.1. Kerberos Principal Name Form ..................... 18 81 4.1.2. Exported Name Object Form for Kerberos5 82 Mechanism ........................................ 19 83 5. Credentials ................................................ 20 84 6. Parameter Definitions ...................................... 20 85 6.1. Minor Status Codes .................................... 20 86 6.1.1. Non-Kerberos-specific codes ...................... 21 87 6.1.2. Kerberos-specific-codes .......................... 21 88 7. Kerberos Protocol Dependencies ............................. 22 89 8. Security Considerations .................................... 22 90 9. References ................................................. 22 91 10. Author's Address .......................................... 23 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114Yu Document Expiration: 04 Sep 2000 [Page 2] 115 116Internet-Draft krb5-gss-mech2-03 March 2000 117 1181. Introduction 119 120 The original Kerberos 5 GSSAPI mechanism[RFC1964] has a number of 121 shortcomings. This document attempts to remedy them by defining a 122 completely new Kerberos 5 GSSAPI mechanism. 123 124 The context establishment token format requires that the 125 authenticator of AP-REQ messages contain a cleartext data structure 126 in its checksum field, which is a needless and potentially confusing 127 overloading of that field. This is implemented by a special checksum 128 algorithm whose purpose is to copy the input data directly into the 129 checksum field of the authenticator. 130 131 The number assignments for checksum algorithms and for encryption 132 types are inconsistent between the Kerberos protocol and the original 133 GSSAPI mechanism. If new encryption or checksum algorithms are added 134 to the Kerberos protocol at some point, the GSSAPI mechanism will 135 need to be separately updated to use these new algorithms. 136 137 The original mechanism specifies a crude method of key derivation (by 138 using the XOR of the context key with a fixed constant), which is 139 incompatible with newer cryptosystems which specify key derivation 140 procedures themselves. The original mechanism also assumes that both 141 checksums and cryptosystem blocksizes are eight bytes. 142 143 Defining all GSSAPI tokens for the new Kerberos 5 mechanism in terms 144 of the Kerberos protocol specification ensures that new encryption 145 types and checksum types may be automatically used as they are 146 defined for the Kerberos protocol. 147 1482. Token Formats 149 150 All tokens, not just the initial token, are framed as the 151 InitialContextToken described in RFC 2743 section 3.1. The 152 innerContextToken element of the token will not itself be encoded in 153 ASN.1, with the exception of caller-provided application data. 154 155 One rationale for avoiding the use of ASN.1 in the inner token is 156 that some implementors may wish to implement this mechanism in a 157 kernel or other similarly constrained application where handling of 158 full ASN.1 encoding may be cumbersome. Also, due to the poor 159 availability of the relevant standards documents, ASN.1 encoders and 160 decoders are difficult to implement completely correctly, so keeping 161 ASN.1 usage to a minimum decreases the probability of bugs in the 162 implementation of the mechanism. In particular, bit strings need to 163 be transferred at certain points in this mechanism. There are many 164 conflicting common misunderstandings of how to encode and decode 165 ASN.1 bit strings, which have led difficulties in the implementaion 166 of the Kerberos protocol. 167 168 169 170 171 172Yu Document Expiration: 04 Sep 2000 [Page 3] 173 174Internet-Draft krb5-gss-mech2-03 March 2000 175 1762.1. Packet Notation 177 178 The order of transmission of this protocol is described at the octet 179 level. Packet diagrams depict bits in the order of transmission, 180 assuming that individual octets are transmitted with the most 181 significant bit (MSB) first. The diagrams read from left to right 182 and from top to bottom, as in printed English. In each octet, bit 183 number 7 is the MSB and bit number 0 is the LSB. 184 185 Numbers prefixed by the characters "0x" are in hexadecimal notation, 186 as in the C programming language. Even though packet diagrams are 187 drawn 16 bits wide, no padding should be used to align the ends of 188 variable-length fields to a 32-bit or 16-bit boundary. 189 190 All integer fields are in network byte order. All other fields have 191 the size shown in the diagrams, with the exception of variable length 192 fields. 193 1942.2. Mechanism OID 195 196 The Object Identifier (OID) of the new krb5 v2 mechanism is: 197 198 {iso(1) member-body(2) us(840) mit(113554) infosys(1) gssapi(2) 199 krb5v2(3)} 200 201 2022.3. Context Establishment 203 2042.3.1. Option Format 205 206 Context establishment tokens, i.e., the initial ones that the 207 GSS_Init_sec_context() and the GSS_Accept_sec_context() calls emit 208 while a security context is being set up, may contain options that 209 influence the subsequent behavior of the context. This document 210 describes only a small set of options, but additional types may be 211 added by documents intended to supplement this one. The generic 212 format is as follows: 213 214 bit| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 215byte +-------------------------------+-------------------------------+ 216 0 | option type | 217 +-------------------------------+-------------------------------+ 218 2 | | 219 +-- option length (32 bits) --+ 220 4 | | 221 +-------------------------------+-------------------------------+ 222 6 | . | 223 / option data (variable length) / 224 | . | 225 +-------------------------------+-------------------------------+ 226 227 228 229 230Yu Document Expiration: 04 Sep 2000 [Page 4] 231 232Internet-Draft krb5-gss-mech2-03 March 2000 233 234 option type (16 bits) 235 The type identifier of the following option. 236 237 option length (32 bits) 238 The length in bytes of the following option. 239 240 option data (variable length) 241 The actual option data. 242 243 Any number of options may appear in an initator or acceptor token. 244 The final option in a token must be the null option, in order to mark 245 the end of the list. Option type 0xffff is reserved. 246 247 The initiator and acceptor shall ignore any options that they do not 248 understand. 249 2502.3.1.1. Delegated Credentials Option 251 252 Only the initiator may use this option. The format of the delegated 253 credentials option is as follows: 254 255 bit| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 256byte +-------------------------------+-------------------------------+ 257 0 | option type = 0x00001 | 258 +-------------------------------+-------------------------------+ 259 2 | | 260 +-- KRB-CRED length --+ 261 4 | | 262 +-------------------------------+-------------------------------+ 263 6 | . | 264 / KRB-CRED message / 265 | . | 266 +-------------------------------+-------------------------------+ 267 268 269 option type (16 bits) 270 The option type for this option shall be 0x0001. 271 272 KRB-CRED length (32 bits) 273 The length in bytes of the following KRB-CRED message. 274 275 KRB-CRED message (variable length) 276 The option data for this option shall be the KRB-CRED message 277 that contains the credentials being delegated (forwarded) to the 278 context acceptor. Only the initiator may use this option. 279 2802.3.1.2. Null Option 281 282 The Null option terminates the option list, and must be used by both 283 the initiator and the acceptor. Its format is as follows: 284 285 286 287 288Yu Document Expiration: 04 Sep 2000 [Page 5] 289 290Internet-Draft krb5-gss-mech2-03 March 2000 291 292 bit| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 293byte +-------------------------------+-------------------------------+ 294 0 | option type = 0 | 295 +-------------------------------+-------------------------------+ 296 2 | | 297 +-- length = 0 --+ 298 4 | | 299 +-------------------------------+-------------------------------+ 300 301 302 option type (16 bits) 303 The option type of this option must be zero. 304 305 option length (32 bits) 306 The length of this option must be zero. 307 3082.3.2. Initial Token 309 310 This is the initial token sent by the context initiator, generated by 311 GSS_Init_sec_context(). 312 313 bit| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 314byte +-------------------------------+-------------------------------+ 315 0 | initial token id = 0x0101 | 316 +-------------------------------+-------------------------------+ 317 2 | | 318 +-- reserved flag bits +-----------------------+ 319 4 | | I | C | S | R | M | D | 320 +-------------------------------+-------------------------------+ 321 6 | checksum type count | 322 +-------------------------------+-------------------------------+ 323 8 | . | 324 / checksum type list / 325 | . | 326 +-------------------------------+-------------------------------+ 327 n | . | 328 / options / 329 | . | 330 +-------------------------------+-------------------------------+ 331 m | | 332 +-- AP-REQ length --+ 333 m+2 | | 334 +-------------------------------+-------------------------------+ 335 m+4 | . | 336 / AP-REQ data / 337 | . | 338 +-------------------------------+-------------------------------+ 339 340 341 initial token ID (16 bits) 342 Contains the integer 0x0101, which identifies this as the 343 initial token in the context setup. 344 345 346Yu Document Expiration: 04 Sep 2000 [Page 6] 347 348Internet-Draft krb5-gss-mech2-03 March 2000 349 350 reserved flag bits (26 bits) 351 These bits are reserved for future expansion. They must be set 352 to zero by the initiator and be ignored by the acceptor. 353 354 I flag (1 bit) 355 0x00000020 -- GSS_C_INTEG_FLAG 356 357 C flag (1 bit) 358 0x00000010 -- GSS_C_CONF_FLAG 359 360 S flag (1 bit) 361 0x00000008 -- GSS_C_SEQUENCE_FLAG 362 363 R flag (1 bit) 364 0x00000004 -- GSS_C_REPLAY_FLAG 365 366 M flag (1 bit) 367 0x00000002 -- GSS_C_MUTUAL_FLAG 368 369 D flag (1 bit) 370 0x00000001 -- GSS_C_DELEG_FLAG; This flag must be set if the 371 "delegated credentials" option is included. 372 373 checksum type count (16 bits) 374 The number of checksum types supported by the initiator. 375 376 checksum type list (variable length) 377 A list of Kerberos checksum types, as defined in RFC 1510 378 section 6.4. These checksum types must be collision-proof and 379 keyed with the context key; no checksum types that are 380 incompatible with the encryption key shall be used. Each 381 checksum type number shall be 32 bits wide. This list should 382 contain all the checksum types supported by the initiator. If 383 mutual authentication is not used, then this list shall contain 384 only one checksum type. 385 386 options (variable length) 387 The context initiation options, described in section 2.3.1. 388 389 AP-REQ length (32 bits) 390 The length of the following KRB_AP_REQ message. 391 392 AP-REQ data (variable length) 393 The AP-REQ message as described in RFC 1510. The checksum in 394 the authenticator will be computed over the items listed in the 395 next section. 396 397 The optional sequence number field shall be used in the AP-REQ. The 398 initiator should generate a subkey in the authenticator, and the 399 acceptor should generate a subkey in the AP-REP. The key used for 400 the per-message tokens will be the AP-REP subkey, or if that is not 401 present, the authenticator subkey, or if that is not present, the 402 session key. When subkeys are generated, it is strongly recommended 403 404Yu Document Expiration: 04 Sep 2000 [Page 7] 405 406Internet-Draft krb5-gss-mech2-03 March 2000 407 408 that they be of the same type as the associated session key. 409 410 XXX The above is not secure. There should be an algorithmic process 411 to arrive at a subsession key which both sides of the authentication 412 exchange can perform based on the ticket sessions key and data known 413 to both parties, and this should probably be part of the revised 414 Kerberos protocol rather than bound to the GSSAPI mechanism. 415 4162.3.2.1. Data to be Checksummed in AP-REQ 417 418 The checksum in the AP-REQ message is calculated over the following 419 items. Like in the actual tokens, no padding should be added to 420 force integer fields to align on 32 bit boundaries. This particular 421 set of data should not be sent as a part of any token; it merely 422 specifies what is to be checksummed in the AP-REQ. The items in this 423 encoding that precede the initial token ID correspond to the channel 424 bindings passed to GSS_Init_sec_context(). 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462Yu Document Expiration: 04 Sep 2000 [Page 8] 463 464Internet-Draft krb5-gss-mech2-03 March 2000 465 466 bit| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 467byte +-------------------------------+-------------------------------+ 468 0 | | 469 +-- initiator address type --+ 470 2 | | 471 +-------------------------------+-------------------------------+ 472 4 | initiator address length | 473 +-------------------------------+-------------------------------+ 474 6 | . | 475 / initiator address / 476 | . | 477 +-------------------------------+-------------------------------+ 478 n | | 479 +-- acceptor address type --+ 480 | | 481 +-------------------------------+-------------------------------+ 482 n+4 | acceptor address length | 483 +-------------------------------+-------------------------------+ 484 n+6 | . | 485 / acceptor address / 486 | . | 487 +-------------------------------+-------------------------------+ 488 m | . | 489 / application data / 490 | . | 491 +-------------------------------+-------------------------------+ 492 k | initial token id = 0x0101 | 493 +-------------------------------+-------------------------------+ 494 k+2 | | 495 +-- flags --+ 496 k+4 | | 497 +-------------------------------+-------------------------------+ 498 k+6 | checksum type count | 499 +-------------------------------+-------------------------------+ 500 k+8 | . | 501 / checksum type list / 502 | . | 503 +-------------------------------+-------------------------------+ 504 j | . | 505 / options / 506 | . | 507 +-------------------------------+-------------------------------+ 508 509 510 initiator address type (32 bits) 511 The initiator address type, as defined in the Kerberos protocol 512 specification. If no initiator address is provided, this must 513 be zero. 514 515 initiator address length (16 bits) 516 The length in bytes of the following initiator address. If 517 there is no inititator address provided, this must be zero. 518 519 520Yu Document Expiration: 04 Sep 2000 [Page 9] 521 522Internet-Draft krb5-gss-mech2-03 March 2000 523 524 initiator address (variable length) 525 The actual initiator address, in network byte order. 526 527 acceptor address type (32 bits) 528 The acceptor address type, as defined in the Kerberos protocol 529 specification. If no acceptor address is provided, this must be 530 zero. 531 532 acceptor address length (16 bits) 533 The length in bytes of the following acceptor address. This 534 must be zero is there is no acceptor address provided. 535 536 initiator address (variable length) 537 The actual acceptor address, in network byte order. 538 539 applicatation data (variable length) 540 The application data, if provided, encoded as a ASN.1 octet 541 string using DER. If no application data are passed as input 542 channel bindings, this shall be a zero-length ASN.1 octet 543 string. 544 545 initial token ID (16 bits) 546 The initial token ID from the initial token. 547 548 flags (32 bits) 549 The context establishment flags from the initial token. 550 551 checksum type count (16 bits) 552 The number of checksum types supported by the initiator. 553 554 checksum type list (variable length) 555 The same list of checksum types contained in the initial token. 556 557 options (variable length) 558 The options list from the initial token. 559 5602.3.3. Response Token 561 562 This is the reponse token sent by the context acceptor, if mutual 563 authentication is enabled. 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578Yu Document Expiration: 04 Sep 2000 [Page 10] 579 580Internet-Draft krb5-gss-mech2-03 March 2000 581 582 bit| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 583byte +-------------------------------+-------------------------------+ 584 0 | response token id = 0x0202 | 585 +-------------------------------+-------------------------------+ 586 2 | | 587 +-- reserved flag bits +-------+ 588 4 | | D | E | 589 +-------------------------------+-------------------------------+ 590 6 | | 591 +-- checksum type --+ 592 8 | | 593 +-------------------------------+-------------------------------+ 594 10 | . | 595 / options / 596 | . | 597 +-------------------------------+-------------------------------+ 598 n | | 599 +-- AP-REP or KRB-ERROR length --+ 600 n+2 | | 601 +-------------------------------+-------------------------------+ 602 n+4 | . | 603 / AP-REP or KRB-ERROR data / 604 | . | 605 +-------------------------------+-------------------------------+ 606 m | . | 607 / MIC data / 608 | . | 609 +-------------------------------+-------------------------------+ 610 611 612 response token id (16 bits) 613 Contains the integer 0x0202, which identifies this as the 614 response token in the context setup. 615 616 reserved flag bits (30 bits) 617 These bits are reserved for future expansion. They must be set 618 to zero by the acceptor and be ignored by the initiator. 619 620 D flag -- delegated creds accepted (1 bit) 621 0x00000002 -- If this flag is set, the acceptor processed the 622 delegated credentials, and GSS_C_DELEG_FLAG should be returned 623 to the caller. 624 625 E flag -- error (1 bit) 626 0x00000001 -- If this flag is set, a KRB-ERROR message shall be 627 present, rather than an AP-REP message. If this flag is not 628 set, an AP-REP message shall be present. 629 630 checksum type count (16 bits) 631 The number of checksum types supported by both the initiator and 632 the acceptor. 633 634 635 636Yu Document Expiration: 04 Sep 2000 [Page 11] 637 638Internet-Draft krb5-gss-mech2-03 March 2000 639 640 checksum type (32 bits) 641 A Kerberos checksum type, as defined in RFC 1510 section 6.4. 642 This checksum type must be among the types listed by the 643 initiator, and will be used in for subsequent checksums 644 generated during this security context. 645 646 options (variable length) 647 The option list, as described earlier. At this time, no options 648 are defined for the acceptor, but an implementation might make 649 use of these options to acknowledge an option from the initial 650 token. After all the options are specified, a null option must 651 be used to terminate the list. 652 653 AP-REP or KRB-ERROR length (32 bits) 654 Depending on the value of the error flag, length in bytes of the 655 AP-REP or KRB-ERROR message. 656 657 AP-REP or KRB-ERROR data (variable length) 658 Depending on the value of the error flag, the AP-REP or 659 KRB-ERROR message as described in RFC 1510. If this field 660 contains an AP-REP message, the sequence number field in the 661 AP-REP shall be filled. If this is a KRB-ERROR message, no 662 further fields will be in this message. 663 664 MIC data (variable length) 665 A MIC token, as described in section 2.4.2, computed over the 666 concatentation of the response token ID, flags, checksum length 667 and type fields, and all option fields. This field and the 668 preceding length field must not be present if the error flag is 669 set. 670 6712.4. Per-message Tokens 672 6732.4.1. Sequence Number Usage 674 675 Sequence numbers for per-message tokens are 31 bit unsigned integers, 676 which are incremented by 1 after each token. An overflow condition 677 should result in a wraparound of the sequence number to zero. The 678 initiator and acceptor each keep their own sequence numbers per 679 connection. 680 681 The intial sequence number for tokens sent from the initiator to the 682 acceptor shall be the least significant 31 bits of sequence number in 683 the AP-REQ message. The initial sequence number for tokens sent from 684 the acceptor to the initiator shall be the least significant 31 bits 685 of the sequence number in the AP-REP message if mutual authentication 686 is used; if mutual authentication is not used, the initial sequence 687 number from acceptor to initiator shall be the least significant 31 688 bits of the sequence number in the AP-REQ message. 689 690 691 692 693 694Yu Document Expiration: 04 Sep 2000 [Page 12] 695 696Internet-Draft krb5-gss-mech2-03 March 2000 697 6982.4.2. MIC Token 699 700 Use of the GSS_GetMIC() call yields a token, separate from the user 701 data being protected, which can be used to verify the integrity of 702 that data when it is received. The MIC token has the following 703 format: 704 705 bit| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 706byte +-------------------------------+-------------------------------+ 707 0 | MIC token id = 0x0303 | 708 +-------------------------------+-------------------------------+ 709 2 | D | | 710 +---+ sequence number --+ 711 4 | | 712 +-------------------------------+-------------------------------+ 713 6 | checksum length | 714 +-------------------------------+-------------------------------+ 715 8 | . | 716 / checksum data / 717 | . | 718 +-------------------------------+-------------------------------+ 719 720 721 MIC token id (16 bits) 722 Contains the integer 0x0303, which identifies this as a MIC 723 token. 724 725 D -- direction bit (1 bit) 726 This bit shall be zero if the message is sent from the context 727 initiator. If the message is sent from the context acceptor, 728 this bit shall be one. 729 730 sequence number (31 bits) 731 The sequence number. 732 733 checksum length (16 bits) 734 The number of bytes in the following checksum data field. 735 736 checksum data (variable length) 737 The checksum itself, as defined in RFC 1510 section 6.4. The 738 checksum is calculated over the encoding described in the 739 following section. The key usage GSS_TOK_MIC -- 22 [XXX need to 740 register this] shall be used in cryptosystems that support key 741 derivation. 742 743 The mechanism implementation shall only use the checksum type 744 returned by the acceptor in the case of mutual authentication. If 745 mutual authentication is not requested, then only the checksum type 746 in the initiator token shall be used. 747 748 749 750 751 752Yu Document Expiration: 04 Sep 2000 [Page 13] 753 754Internet-Draft krb5-gss-mech2-03 March 2000 755 7562.4.2.1. Data to be Checksummed in MIC Token 757 758 The checksum in the MIC token shall be calculated over the following 759 elements. This set of data is not actually included in the token as 760 is; the description only appears for the purpose of specifying the 761 method of calculating the checksum. 762 763 bit| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 764byte +-------------------------------+-------------------------------+ 765 0 | MIC token id = 0x0303 | 766 +-------------------------------+-------------------------------+ 767 2 | D | | 768 +---+ sequence number --+ 769 4 | | 770 +-------------------------------+-------------------------------+ 771 6 | . | 772 / application data / 773 | . | 774 +-------------------------------+-------------------------------+ 775 776 777 MIC token ID (16 bits) 778 The MIC token ID from the MIC message. 779 780 D -- direction bit (1 bit) 781 This bit shall be zero if the message is sent from the context 782 initiator. If the message is sent from the context acceptor, 783 this bit shall be one. 784 785 sequence number (31 bits) 786 The sequence number. 787 788 application data (variable length) 789 The application-supplied data, encoded as an ASN.1 octet string 790 using DER. 791 7922.4.3. Wrap Token 793 794 Use of the GSS_Wrap() call yields a token which encapsulates the 795 input user data (optionally encrypted) along with associated 796 integrity check quantities. 797 7982.4.3.1. Wrap Token With Integrity Only 799 800 801 802 803 804 805 806 807 808 809 810Yu Document Expiration: 04 Sep 2000 [Page 14] 811 812Internet-Draft krb5-gss-mech2-03 March 2000 813 814 bit| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 815byte +-------------------------------+-------------------------------+ 816 0 | integrity wrap token id = 0x0404 | 817 +-------------------------------+-------------------------------+ 818 2 | D | | 819 +---+ sequence number --+ 820 4 | | 821 +-------------------------------+-------------------------------+ 822 6 | . | 823 / application data / 824 | . | 825 +-------------------------------+-------------------------------+ 826 n | checksum length | 827 +-------------------------------+-------------------------------+ 828 n+2 | . | 829 / checksum data / 830 | . | 831 +-------------------------------+-------------------------------+ 832 833 834 integrity wrap token id (16 bits) 835 Contains the integer 0x0404, which identifies this as a Wrap 836 token with integrity only. 837 838 D -- direction bit (1 bit) 839 This bit shall be zero if the message is sent from the context 840 initiator. If the message is sent from the context acceptor, 841 this bit shall be one. 842 843 sequence number (31 bits) 844 The sequence number. 845 846 application data (variable length) 847 The application-supplied data, encoded as an ASN.1 octet string 848 using DER. 849 850 checksum length (16 bits) 851 The number of bytes in the following checksum data field. 852 853 checksum data (variable length) 854 The checksum itself, as defined in RFC 1510 section 6.4, 855 computed over the concatenation of the token ID, sequence 856 number, direction field, application data length, and 857 application data, as in the MIC token checksum in the previous 858 section. The key usage GSS_TOK_WRAP_INTEG -- 23 [XXX need to 859 register this] shall be used in cryptosystems that support key 860 derivation. 861 862 The mechanism implementation should only use checksum types which it 863 knows to be valid for both peers, as described for MIC tokens. 864 865 866 867 868Yu Document Expiration: 04 Sep 2000 [Page 15] 869 870Internet-Draft krb5-gss-mech2-03 March 2000 871 8722.4.3.2. Wrap Token With Integrity and Encryption 873 874 bit| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 875byte +-------------------------------+-------------------------------+ 876 | encrypted wrap token id = 0x0505 | 877 +-------------------------------+-------------------------------+ 878 2 | . | 879 / encrypted data / 880 | . | 881 +-------------------------------+-------------------------------+ 882 883 884 encrypted wrap token id (16 bits) 885 Contains the integer 0x0505, which identifies this as a Wrap 886 token with integrity and encryption. 887 888 encrypted data (variable length) 889 The encrypted data itself, as defined in RFC 1510 section 6.3, 890 encoded as an ASN.1 octet string using DER. Note that this is 891 not the ASN.1 type EncryptedData as defined in RFC 1510 892 section 6.1, but rather the ciphertext without encryption type 893 or kvno information. The encryption is performed using the 894 key/enctype exchanged during context setup. The confounder and 895 checksum are as specified in the Kerberos protocol 896 specification. The key usage GSS_TOK_WRAP_PRIV -- 24 [XXX need 897 to register this] shall be used in cryptosystems that support 898 key derivation. The actual data to be encrypted are specified 899 below. 900 9012.4.3.2.1. Data to be Encrypted in Wrap Token 902 903 bit| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 904byte +-------------------------------+-------------------------------+ 905 0 | D | | 906 +---+ sequence number --+ 907 2 | | 908 +-------------------------------+-------------------------------+ 909 4 | . | 910 / application data / 911 | . | 912 +-------------------------------+-------------------------------+ 913 914 915 D -- direction bit (1 bit) 916 This bit shall be zero if the message is sent from the context 917 initiator. If the message is sent from the context acceptor, 918 this bit shall be one. 919 920 sequence number (31 bits) 921 The sequence number. 922 923 application data (variable length) 924 The application-supplied data, encoded as an ASN.1 octet string 925 926Yu Document Expiration: 04 Sep 2000 [Page 16] 927 928Internet-Draft krb5-gss-mech2-03 March 2000 929 930 using DER. 931 9323. ASN.1 Encoding of Octet Strings 933 934 In order to encode arbitirarly-sized application data, ASN.1 octet 935 string encoding is in this protocol. The Distinguished Encoding 936 Rules (DER) shall always be used in such cases. For reference 937 purposes, the DER encoding of an ASN.1 octet string, adapted from 938 ITU-T X.690, follows: 939 940 +--------+-------//-------+-------//-------+ 941 |00000100| length octets |contents octets | 942 +--------+-------//-------+-------//-------+ 943 | 944 +-- identifier octet = 0x04 = [UNIVERSAL 4] 945 946 947 In this section only, the bits in each octet shall be numbered as in 948 the ASN.1 specification, from 8 to 1, with bit 8 being the MSB of the 949 octet, and with bit 1 being the LSB of the octet. 950 951 identifier octet (8 bits) 952 Contains the constant 0x04, the tag for primitive encoding of an 953 octet string with the default (UNIVERSAL 4) tag. 954 955 length octets (variable length) 956 Contains the length of the contents octets, in definite form 957 (since this encoding uses DER). 958 959 contents octets (variable length) 960 The contents of the octet string. 961 962 The length octets shall consist of either a short form (one byte 963 only), which is to be used only if the number of octets in the 964 contents octets is less than or equal to 127, or a long form, which 965 is to be used in all other cases. The short form shall consist of a 966 single octet with bit 8 (the MSB) equal to zero, and the remaining 967 bits encoding the number of contents octets (which may be zero) as an 968 unsigned binary integer. 969 970 The long form shall consist of an initial octet and one or more 971 subsequent octets. The first octet shall have bit 8 (the MSB) set to 972 one, and the remaining bits shall encode the number of subsequent 973 octets in the length encoding as an unsigned binary integer. The 974 length must be encoded in the minimum number of octets. An initial 975 octet of 0xFF is reserved by the ASN.1 specification. Bits 8 to 1 of 976 the first subsequent octet, followed by bits 8 to 1 of each 977 subsequent octet in order, shall be the encoding of an unsigned 978 binary integer, with bit 8 of the first octet being the most 979 significant bit. Thus, the length encoding within is in network byte 980 order. 981 982 983 984Yu Document Expiration: 04 Sep 2000 [Page 17] 985 986Internet-Draft krb5-gss-mech2-03 March 2000 987 988 An initial length octet of 0x80 shall not be used, as that is 989 reserved by the ASN.1 specification for indefinite lengths in 990 conjunction with constructed contents encodings, which are not to be 991 used with DER. 992 9934. Name Types 994 995 This section discusses the name types which may be passed as input to 996 the Kerberos 5 GSSAPI mechanism's GSS_Import_name() call, and their 997 associated identifier values. It defines interface elements in 998 support of portability, and assumes use of C language bindings per 999 RFC 2744. In addition to specifying OID values for name type 1000 identifiers, symbolic names are included and recommended to GSSAPI 1001 implementors in the interests of convenience to callers. It is 1002 understood that not all implementations of the Kerberos 5 GSSAPI 1003 mechanism need support all name types in this list, and that 1004 additional name forms will likely be added to this list over time. 1005 Further, the definitions of some or all name types may later migrate 1006 to other, mechanism-independent, specifications. The occurrence of a 1007 name type in this specification is specifically not intended to 1008 suggest that the type may be supported only by an implementation of 1009 the Kerberos 5 mechanism. In particular, the occurrence of the 1010 string "_KRB5_" in the symbolic name strings constitutes a means to 1011 unambiguously register the name strings, avoiding collision with 1012 other documents; it is not meant to limit the name types' usage or 1013 applicability. 1014 1015 For purposes of clarification to GSSAPI implementors, this section's 1016 discussion of some name forms describes means through which those 1017 forms can be supported with existing Kerberos technology. These 1018 discussions are not intended to preclude alternative implementation 1019 strategies for support of the name forms within Kerberos mechanisms 1020 or mechanisms based on other technologies. To enhance application 1021 portability, implementors of mechanisms are encouraged to support 1022 name forms as defined in this section, even if their mechanisms are 1023 independent of Kerberos 5. 1024 10254.1. Mandatory Name Forms 1026 1027 This section discusses name forms which are to be supported by all 1028 conformant implementations of the Kerberos 5 GSSAPI mechanism. 1029 10304.1.1. Kerberos Principal Name Form 1031 1032 This name form shall be represented by the Object Identifier {iso(1) 1033 member-body(2) us(840) mit(113554) infosys(1) gssapi(2) krb5(2) 1034 krb5_name(1)}. The recommended symbolic name for this type is 1035 "GSS_KRB5_NT_PRINCIPAL_NAME". 1036 1037 This name type corresponds to the single-string representation of a 1038 Kerberos name. (Within the MIT Kerberos 5 implementation, such names 1039 are parseable with the krb5_parse_name() function.) The elements 1040 included within this name representation are as follows, proceeding 1041 1042Yu Document Expiration: 04 Sep 2000 [Page 18] 1043 1044Internet-Draft krb5-gss-mech2-03 March 2000 1045 1046 from the beginning of the string: 1047 1048 (1) One or more principal name components; if more than one 1049 principal name component is included, the components are 1050 separated by '/'. Arbitrary octets may be included within 1051 principal name components, with the following constraints and 1052 special considerations: 1053 1054 (1a) Any occurrence of the characters '@' or '/' within a 1055 name component must be immediately preceded by the '\' 1056 quoting character, to prevent interpretation as a component 1057 or realm separator. 1058 1059 (1b) The ASCII newline, tab, backspace, and null characters 1060 may occur directly within the component or may be 1061 represented, respectively, by '\n', '\t', '\b', or '\0'. 1062 1063 (1c) If the '\' quoting character occurs outside the contexts 1064 described in (1a) and (1b) above, the following character is 1065 interpreted literally. As a special case, this allows the 1066 doubled representation '\\' to represent a single occurrence 1067 of the quoting character. 1068 1069 (1d) An occurrence of the '\' quoting character as the last 1070 character of a component is illegal. 1071 1072 (2) Optionally, a '@' character, signifying that a realm name 1073 immediately follows. If no realm name element is included, the 1074 local realm name is assumed. The '/' , ':', and null characters 1075 may not occur within a realm name; the '@', newline, tab, and 1076 backspace characters may be included using the quoting 1077 conventions described in (1a), (1b), and (1c) above. 1078 10794.1.2. Exported Name Object Form for Kerberos 5 Mechanism 1080 1081 When generated by the Kerberos 5 mechanism, the Mechanism OID within 1082 the exportable name shall be that of the original Kerberos 5 1083 mechanism[RFC1964]. The Mechanism OID for the original Kerberos 5 1084 mechanism is: 1085 1086 {iso(1) member-body(2) us(840) mit(113554) infosys(1) gssapi(2) 1087 krb5(2)} 1088 1089 The name component within the exportable name shall be a contiguous 1090 string with structure as defined for the Kerberos Principal Name 1091 Form. 1092 1093 In order to achieve a distinguished encoding for comparison purposes, 1094 the following additional constraints are imposed on the export 1095 operation: 1096 1097 (1) all occurrences of the characters '@', '/', and '\' within 1098 principal components or realm names shall be quoted with an 1099 1100Yu Document Expiration: 04 Sep 2000 [Page 19] 1101 1102Internet-Draft krb5-gss-mech2-03 March 2000 1103 1104 immediately-preceding '\'. 1105 1106 (2) all occurrences of the null, backspace, tab, or newline 1107 characters within principal components or realm names will be 1108 represented, respectively, with '\0', '\b', '\t', or '\n'. 1109 1110 (3) the '\' quoting character shall not be emitted within an 1111 exported name except to accomodate cases (1) and (2). 1112 11135. Credentials 1114 1115 The Kerberos 5 protocol uses different credentials (in the GSSAPI 1116 sense) for initiating and accepting security contexts. Normal 1117 clients receive a ticket-granting ticket (TGT) and an associated 1118 session key at "login" time; the pair of a TGT and its corresponding 1119 session key forms a credential which is suitable for initiating 1120 security contexts. A ticket-granting ticket, its session key, and 1121 any other (ticket, key) pairs obtained through use of the 1122 ticket-granting-ticket, are typically stored in a Kerberos 5 1123 credentials cache, sometimes known as a ticket file. 1124 1125 The encryption key used by the Kerberos server to seal tickets for a 1126 particular application service forms the credentials suitable for 1127 accepting security contexts. These service keys are typically stored 1128 in a Kerberos 5 key table (keytab), or srvtab file (the Kerberos 4 1129 terminology). In addition to their use as accepting credentials, 1130 these service keys may also be used to obtain initiating credentials 1131 for their service principal. 1132 1133 The Kerberos 5 mechanism's credential handle may contain references 1134 to either or both types of credentials. It is a local matter how the 1135 Kerberos 5 mechanism implementation finds the appropriate Kerberos 5 1136 credentials cache or key table. 1137 1138 However, when the Kerberos 5 mechanism attempts to obtain initiating 1139 credentials for a service principal which are not available in a 1140 credentials cache, and the key for that service principal is 1141 available in a Kerberos 5 key table, the mechanism should use the 1142 service key to obtain initiating credentials for that service. This 1143 should be accomplished by requesting a ticket-granting-ticket from 1144 the Kerberos Key Distribution Center (KDC), and decrypting the KDC's 1145 reply using the service key. 1146 11476. Parameter Definitions 1148 1149 This section defines parameter values used by the Kerberos V5 GSSAPI 1150 mechanism. It defines interface elements in support of portability, 1151 and assumes use of C language bindings per RFC 2744. 1152 11536.1. Minor Status Codes 1154 1155 This section recommends common symbolic names for minor_status values 1156 to be returned by the Kerberos 5 GSSAPI mechanism. Use of these 1157 1158Yu Document Expiration: 04 Sep 2000 [Page 20] 1159 1160Internet-Draft krb5-gss-mech2-03 March 2000 1161 1162 definitions will enable independent implementors to enhance 1163 application portability across different implementations of the 1164 mechanism defined in this specification. (In all cases, 1165 implementations of GSS_Display_status() will enable callers to 1166 convert minor_status indicators to text representations.) Each 1167 implementation should make available, through include files or other 1168 means, a facility to translate these symbolic names into the concrete 1169 values which a particular GSSAPI implementation uses to represent the 1170 minor_status values specified in this section. 1171 1172 It is recognized that this list may grow over time, and that the need 1173 for additional minor_status codes specific to particular 1174 implementations may arise. It is recommended, however, that 1175 implementations should return a minor_status value as defined on a 1176 mechanism-wide basis within this section when that code is accurately 1177 representative of reportable status rather than using a separate, 1178 implementation-defined code. 1179 11806.1.1. Non-Kerberos-specific codes 1181 1182 These symbols should likely be incorporated into the generic GSSAPI 1183 C-bindings document, since they really are more general. 1184 1185GSS_KRB5_S_G_BAD_SERVICE_NAME 1186 /* "No @ in SERVICE-NAME name string" */ 1187GSS_KRB5_S_G_BAD_STRING_UID 1188 /* "STRING-UID-NAME contains nondigits" */ 1189GSS_KRB5_S_G_NOUSER 1190 /* "UID does not resolve to username" */ 1191GSS_KRB5_S_G_VALIDATE_FAILED 1192 /* "Validation error" */ 1193GSS_KRB5_S_G_BUFFER_ALLOC 1194 /* "Couldn't allocate gss_buffer_t data" */ 1195GSS_KRB5_S_G_BAD_MSG_CTX 1196 /* "Message context invalid" */ 1197GSS_KRB5_S_G_WRONG_SIZE 1198 /* "Buffer is the wrong size" */ 1199GSS_KRB5_S_G_BAD_USAGE 1200 /* "Credential usage type is unknown" */ 1201GSS_KRB5_S_G_UNKNOWN_QOP 1202 /* "Unknown quality of protection specified" */ 1203 1204 12056.1.2. Kerberos-specific-codes 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216Yu Document Expiration: 04 Sep 2000 [Page 21] 1217 1218Internet-Draft krb5-gss-mech2-03 March 2000 1219 1220GSS_KRB5_S_KG_CCACHE_NOMATCH 1221 /* "Principal in credential cache does not match desired name" */ 1222GSS_KRB5_S_KG_KEYTAB_NOMATCH 1223 /* "No principal in keytab matches desired name" */ 1224GSS_KRB5_S_KG_TGT_MISSING 1225 /* "Credential cache has no TGT" */ 1226GSS_KRB5_S_KG_NO_SUBKEY 1227 /* "Authenticator has no subkey" */ 1228GSS_KRB5_S_KG_CONTEXT_ESTABLISHED 1229 /* "Context is already fully established" */ 1230GSS_KRB5_S_KG_BAD_SIGN_TYPE 1231 /* "Unknown signature type in token" */ 1232GSS_KRB5_S_KG_BAD_LENGTH 1233 /* "Invalid field length in token" */ 1234GSS_KRB5_S_KG_CTX_INCOMPLETE 1235 /* "Attempt to use incomplete security context" */ 1236 1237 12387. Kerberos Protocol Dependencies 1239 1240 This protocol makes several assumptions about the Kerberos protocol, 1241 which may require changes to the successor of RFC 1510. 1242 1243 Sequence numbers, checksum types, and address types are assumed to be 1244 no wider than 32 bits. The Kerberos protocol specification might 1245 need to be modified to accomodate this. This obviously requires some 1246 further discussion. 1247 1248 Key usages need to be registered within the Kerberos protocol for use 1249 with GSSAPI per-message tokens. The current specification of the 1250 Kerberos protocol does not include descriptions of key derivations or 1251 key usages, but planned revisions to the protocol will include them. 1252 1253 This protocol also makes the assumption that any cryptosystem used 1254 with the session key will include integrity protection, i.e., it 1255 assumes that no "raw" cryptosystems will be used. 1256 12578. Security Considerations 1258 1259 The GSSAPI is a security protocol; therefore, security considerations 1260 are discussed throughout this document. The original Kerberos 5 1261 GSSAPI mechanism's constraints on possible cryptosystems and checksum 1262 types do not permit it to be readily extended to accomodate more 1263 secure cryptographic technologies with larger checksums or encryption 1264 block sizes. Sites are strongly encouraged to adopt the mechanism 1265 specified in this document in the light of recent publicity about the 1266 deficiencies of DES. 1267 12689. References 1269 1270 [X.680] ISO/IEC, "Information technology -- Abstract Syntax Notation 1271 One (ASN.1): Specification of basic notation", ITU-T X.680 (1997) | 1272 ISO/IEC 8824-1:1998 1273 1274Yu Document Expiration: 04 Sep 2000 [Page 22] 1275 1276Internet-Draft krb5-gss-mech2-03 March 2000 1277 1278 [X.690] ISO/IEC, "Information technology -- ASN.1 encoding rules: 1279 Specification of Basic Encoding Rules (BER), Canonical Encoding Rules 1280 (CER) and Distinguished Encoding Rules (DER)", ITU-T X.690 (1997) | 1281 ISO/IEC 8825-1:1998. 1282 1283 [RFC1510] Kohl, J., Neumann, C., "The Kerberos Network Authentication 1284 Service (V5)", RFC 1510. 1285 1286 [RFC1964] Linn, J., "The Kerberos Version 5 GSS-API Mechanism", 1287 RFC 1964. 1288 1289 [RFC2743] Linn, J., "Generic Security Service Application Program 1290 Interface, Version 2, Update 1", RFC 2743. 1291 1292 [RFC2744] Wray, J., "Generic Security Service API Version 2: 1293 C-bindings", RFC 2744. 1294 129510. Author's Address 1296 1297 Tom Yu 1298 Massachusetts Institute of Technology 1299 Room E40-345 1300 77 Massachusetts Avenue 1301 Cambridge, MA 02139 1302 USA 1303 1304 email: tlyu@mit.edu 1305 phone: +1 617 253 1753 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332Yu Document Expiration: 04 Sep 2000 [Page 23] 1333 1334