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
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.
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).
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
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-
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]
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
75
{iso(1) member-body(2) United States(840) mit(113554) infosys(1)
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 {
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
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]
116
RFC 1964 Kerberos Version 5 GSS-API June 1996
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,
128
authenticator[4] EncryptedData
131
APOptions ::= BIT STRING {
137
Ticket ::= [APPLICATION 1] SEQUENCE {
138
tkt-vno [0] INTEGER, -- indicates Version 5
140
sname [2] PrincipalName,
141
enc-part [3] EncryptedData
144
-- Encrypted part of ticket
145
EncTicketPart ::= [APPLICATION 3] SEQUENCE {
146
flags[0] TicketFlags,
147
key[1] EncryptionKey,
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
159
-- Unencrypted authenticator
160
Authenticator ::= [APPLICATION 2] SEQUENCE {
161
authenticator-vno[0] INTEGER,
163
cname[2] PrincipalName,
164
cksum[3] Checksum OPTIONAL,
166
ctime[5] KerberosTime,
170
Linn Standards Track [Page 3]
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
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
203
20..23 Flags Bit vector of context-establishment flags,
204
with values consistent with RFC-1509, p. 41:
208
GSS_C_SEQUENCE_FLAG: 8
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
220
(1) Each integer field shall be formatted into four bytes, using
221
little-endian byte ordering, for purposes of MD5 hash
226
Linn Standards Track [Page 4]
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
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
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]
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
300
EncAPRepPart ::= [APPLICATION 27] SEQUENCE {
301
ctime [0] KerberosTime,
303
subkey [2] EncryptionKey OPTIONAL,
304
seq-number [3] INTEGER OPTIONAL
307
The optional seq-number element within the AP-REP's EncAPRepPart
310
The syntax of KRB_ERROR is as follows:
312
KRB-ERROR ::= [APPLICATION 30] SEQUENCE {
315
ctime[2] KerberosTime OPTIONAL,
316
cusec[3] INTEGER OPTIONAL,
317
stime[4] KerberosTime,
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
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]
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
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.
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]
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.
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
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
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
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]
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
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
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]
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.
525
4..5 SEAL_ALG ff ff - none
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.
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]
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.
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
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
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]
620
RFC 1964 Kerberos Version 5 GSS-API June 1996
623
Byte no Name Description
624
0..1 TOK_ID Identification field.
626
GSS_Delete_sec_context() contain
627
the hex value 01 02 in this field.
628
2..3 SGN_ALG Integrity algorithm indicator.
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
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]
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
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]
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:
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
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]
788
RFC 1964 Kerberos Version 5 GSS-API June 1996
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
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
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]
844
RFC 1964 Kerberos Version 5 GSS-API June 1996
847
Its interpretation is OS-specific. This name form is constructed as:
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]
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]
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" */
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]
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().
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
1066
Linn Standards Track [Page 19]
1068
RFC 1964 Kerberos Version 5 GSS-API June 1996
1071
5. Security Considerations
1073
Security issues are discussed throughout this memo.
1078
[RFC-1321]: Rivest, R., "The MD5 Message-Digest Algorithm", RFC
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.
1096
OpenVision Technologies
1098
Cambridge, MA 02142 USA
1100
Phone: +1 617.374.2245
1101
EMail: John.Linn@ov.com
1122
Linn Standards Track [Page 20]
added
removed
doc/standardisation/rfc1964.txt
