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