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