remove gcc34
[dragonfly.git] / crypto / heimdal-0.6.3 / doc / standardisation / draft-ietf-cat-krb5gss-mech2-03.txt
1
2 INTERNET-DRAFT                                                    Tom Yu
3 Common Authentication Technology WG                                  MIT
4 draft-ietf-cat-krb5gss-mech2-03.txt                        04 March 2000
5
6            The Kerberos Version 5 GSSAPI Mechanism, Version 2
7
8 Status 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
33 Abstract
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
41 Acknowledgements
42
43    Much of the material in this specification is based on work done for
44    Cygnus Solutions by Marc Horowitz.
45
46 Table 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
56 Yu                  Document Expiration: 04 Sep 2000            [Page 1]
57 \f
58 Internet-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
114 Yu                  Document Expiration: 04 Sep 2000            [Page 2]
115 \f
116 Internet-Draft             krb5-gss-mech2-03                  March 2000
117
118 1.  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
148 2.  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
172 Yu                  Document Expiration: 04 Sep 2000            [Page 3]
173 \f
174 Internet-Draft             krb5-gss-mech2-03                  March 2000
175
176 2.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
194 2.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
202 2.3.  Context Establishment
203
204 2.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 |
215 byte +-------------------------------+-------------------------------+
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
230 Yu                  Document Expiration: 04 Sep 2000            [Page 4]
231 \f
232 Internet-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
250 2.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 |
256 byte +-------------------------------+-------------------------------+
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
280 2.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
288 Yu                  Document Expiration: 04 Sep 2000            [Page 5]
289 \f
290 Internet-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 |
293 byte +-------------------------------+-------------------------------+
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
308 2.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 |
314 byte +-------------------------------+-------------------------------+
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
346 Yu                  Document Expiration: 04 Sep 2000            [Page 6]
347 \f
348 Internet-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
404 Yu                  Document Expiration: 04 Sep 2000            [Page 7]
405 \f
406 Internet-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
416 2.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
462 Yu                  Document Expiration: 04 Sep 2000            [Page 8]
463 \f
464 Internet-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 |
467 byte +-------------------------------+-------------------------------+
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
520 Yu                  Document Expiration: 04 Sep 2000            [Page 9]
521 \f
522 Internet-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
560 2.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
578 Yu                  Document Expiration: 04 Sep 2000           [Page 10]
579 \f
580 Internet-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 |
583 byte +-------------------------------+-------------------------------+
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
636 Yu                  Document Expiration: 04 Sep 2000           [Page 11]
637 \f
638 Internet-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
671 2.4.  Per-message Tokens
672
673 2.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
694 Yu                  Document Expiration: 04 Sep 2000           [Page 12]
695 \f
696 Internet-Draft             krb5-gss-mech2-03                  March 2000
697
698 2.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 |
706 byte +-------------------------------+-------------------------------+
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
752 Yu                  Document Expiration: 04 Sep 2000           [Page 13]
753 \f
754 Internet-Draft             krb5-gss-mech2-03                  March 2000
755
756 2.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 |
764 byte +-------------------------------+-------------------------------+
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
792 2.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
798 2.4.3.1.  Wrap Token With Integrity Only
799
800
801
802
803
804
805
806
807
808
809
810 Yu                  Document Expiration: 04 Sep 2000           [Page 14]
811 \f
812 Internet-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 |
815 byte +-------------------------------+-------------------------------+
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
868 Yu                  Document Expiration: 04 Sep 2000           [Page 15]
869 \f
870 Internet-Draft             krb5-gss-mech2-03                  March 2000
871
872 2.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 |
875 byte +-------------------------------+-------------------------------+
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
901 2.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 |
904 byte +-------------------------------+-------------------------------+
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
926 Yu                  Document Expiration: 04 Sep 2000           [Page 16]
927 \f
928 Internet-Draft             krb5-gss-mech2-03                  March 2000
929
930         using DER.
931
932 3.  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
984 Yu                  Document Expiration: 04 Sep 2000           [Page 17]
985 \f
986 Internet-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
993 4.  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
1025 4.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
1030 4.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
1042 Yu                  Document Expiration: 04 Sep 2000           [Page 18]
1043 \f
1044 Internet-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
1079 4.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
1100 Yu                  Document Expiration: 04 Sep 2000           [Page 19]
1101 \f
1102 Internet-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
1113 5.  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
1147 6.  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
1153 6.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
1158 Yu                  Document Expiration: 04 Sep 2000           [Page 20]
1159 \f
1160 Internet-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
1180 6.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
1185 GSS_KRB5_S_G_BAD_SERVICE_NAME
1186         /* "No @ in SERVICE-NAME name string" */
1187 GSS_KRB5_S_G_BAD_STRING_UID
1188         /* "STRING-UID-NAME contains nondigits" */
1189 GSS_KRB5_S_G_NOUSER
1190         /* "UID does not resolve to username" */
1191 GSS_KRB5_S_G_VALIDATE_FAILED
1192         /* "Validation error" */
1193 GSS_KRB5_S_G_BUFFER_ALLOC
1194         /* "Couldn't allocate gss_buffer_t data" */
1195 GSS_KRB5_S_G_BAD_MSG_CTX
1196         /* "Message context invalid" */
1197 GSS_KRB5_S_G_WRONG_SIZE
1198         /* "Buffer is the wrong size" */
1199 GSS_KRB5_S_G_BAD_USAGE
1200         /* "Credential usage type is unknown" */
1201 GSS_KRB5_S_G_UNKNOWN_QOP
1202         /* "Unknown quality of protection specified" */
1203
1204
1205 6.1.2.  Kerberos-specific-codes
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216 Yu                  Document Expiration: 04 Sep 2000           [Page 21]
1217 \f
1218 Internet-Draft             krb5-gss-mech2-03                  March 2000
1219
1220 GSS_KRB5_S_KG_CCACHE_NOMATCH
1221         /* "Principal in credential cache does not match desired name" */
1222 GSS_KRB5_S_KG_KEYTAB_NOMATCH
1223         /* "No principal in keytab matches desired name" */
1224 GSS_KRB5_S_KG_TGT_MISSING
1225         /* "Credential cache has no TGT" */
1226 GSS_KRB5_S_KG_NO_SUBKEY
1227         /* "Authenticator has no subkey" */
1228 GSS_KRB5_S_KG_CONTEXT_ESTABLISHED
1229         /* "Context is already fully established" */
1230 GSS_KRB5_S_KG_BAD_SIGN_TYPE
1231         /* "Unknown signature type in token" */
1232 GSS_KRB5_S_KG_BAD_LENGTH
1233         /* "Invalid field length in token" */
1234 GSS_KRB5_S_KG_CTX_INCOMPLETE
1235         /* "Attempt to use incomplete security context" */
1236
1237
1238 7.  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
1257 8.  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
1268 9.  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
1274 Yu                  Document Expiration: 04 Sep 2000           [Page 22]
1275 \f
1276 Internet-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
1295 10.  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
1332 Yu                  Document Expiration: 04 Sep 2000           [Page 23]
1333 \f