7 Network Working Group J. Myers
8 Internet Draft Netscape Communications
9 Document: draft-ietf-cat-sasl-gssapi-05.txt May 2001
12 SASL GSSAPI mechanisms
16 Internet-Drafts are working documents of the Internet Engineering
17 Task Force (IETF), its areas, and its working groups. Note that
18 other groups may also distribute working documents as Internet-
21 Internet-Drafts are draft documents valid for a maximum of six months
22 and may be updated, replaced, or obsoleted by other documents at any
23 time. It is inappropriate to use Internet- Drafts as reference
24 material or to cite them other than as "work in progress."
26 The list of current Internet-Drafts can be accessed at
27 http://www.ietf.org/ietf/1id-abstracts.txt
29 The list of Internet-Draft Shadow Directories can be accessed at
30 http://www.ietf.org/shadow.html.
32 This document is an Internet-Draft and is in full conformance with
33 all provisions of Section 10 of RFC2026.
35 A revised version of this draft document will be submitted to the RFC
36 editor as a Proposed Standard for the Internet Community. Discussion
37 and suggestions for improvement are requested.
39 NOTE TO RFC EDITOR: Prior to publication as an RFC, the RFC Editor is
40 directed to replace occurrences of "[THIS-DOC]" with the RFC number
41 assigned to this document.
60 Internet DRAFT GSSAPI SASL mechanisms May 30, 2001
70 Status of this Memo ............................................... i
71 1. Abstract .................................................... 2
72 2. Conventions Used in this Document ........................... 2
73 3. Introduction and Overview ................................... 2
74 3.1 Example ..................................................... 3
75 4. SPNEGO ...................................................... 3
76 5. Base32 encoding ............................................. 3
77 6. Specification common to all GSSAPI mechanisms ............... 5
78 6.1. Client side of authentication protocol exchange ............. 5
79 6.2. Server side of authentication protocol exchange ............. 6
80 6.3. Security layer .............................................. 7
81 7. IANA Considerations ......................................... 7
82 8. References .................................................. 9
83 9. Security Considerations ..................................... 9
84 10. Author's Address ............................................ 10
85 Appendix A. Sample code ........................................... 11
116 Internet DRAFT GSSAPI SASL mechanisms May 30, 2001
121 The Simple Authentication and Security Layer [SASL] is a method for
122 adding authentication support to connection-based protocols. This
123 document describes the method for using the Generic Security Service
124 Application Program Interface [GSSAPI] in the Simple Authentication
125 and Security Layer [SASL].
127 This document replaces section 7.2 of RFC 2222 [SASL], the definition
128 of the "GSSAPI" SASL mechanism.
130 2. Conventions Used in this Document
132 The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY"
133 in this document are to be interpreted as defined in "Key words for
134 use in RFCs to Indicate Requirement Levels" [KEYWORDS].
136 3. Introduction and Overview
138 Each and every GSSAPI mechanism used within SASL is implicitly
139 registered by this specification.
141 For backwards compatibility with existing implementations of Kerberos
142 V5 and SPNEGO under SASL, the SASL mechanism name for the Kerberos V5
143 GSSAPI mechanism [GSSAPI-KERBEROS] is "GSSAPI" and the SASL mechanism
144 for the SPNEGO GSSAPI mechanism [SPNEGO] is "GSS-SPNEGO". The SASL
145 mechanism name for any other GSSAPI mechanism is the concatenation of
146 "GSS-" and the Base32 encoding of the first ten bytes of the MD5 hash
147 [MD5] of the ASN.1 DER encoding [ASN1] of the GSSAPI mechanism's OID.
148 Base32 encoding is described later in this document. The Base32
149 rules on padding characters and characters outside of the base32
150 alphabet are not relevant to this use of Base32.
152 SASL mechanism names starting with "GSS-" are reserved for SASL
153 mechanisms which conform to this document.
155 The specification of all SASL mechanisms conforming to this document
156 is in the "Specification common to all GSSAPI mechanisms" section of
159 The IESG is considered to be the owner of all SASL mechanisms which
160 conform to this document. This does NOT necessarily imply that the
161 IESG is considered to be the owner of the underlying GSSAPI
172 Internet DRAFT GSSAPI SASL mechanisms May 30, 2001
177 The OID for the SPKM-1 mechanism [SPKM] is 1.3.6.1.5.5.1. The ASN.1
178 DER encoding of this OID is 06 06 2b 06 01 05 05 01. The MD5 hash of
179 the ASN.1 DER encoding is 57 ee 81 82 4e ac 4d b0 e6 50 9f 60 1f 46
180 8a 30. The Base32 encoding of the first ten bytes of this is
181 "K7XIDASOVRG3BZSQ". Thus the SASL mechanism name for the SPKM-1
182 GSSAPI mechanism is "GSS-K7XIDASOVRG3BZSQ".
186 Use of the Simple and Protected GSS-API Negotiation Mechanism
187 [SPNEGO] underneath SASL introduces subtle interoperability problems
188 and security considerations. To address these, this section places
189 additional requirements on implementations which support SPNEGO
192 A client which supports, for example, the Kerberos V5 GSSAPI
193 mechanism only underneath SPNEGO underneath the "GSS-SPNEGO" SASL
194 mechanism will not interoperate with a server which supports the
195 Kerberos V5 GSSAPI mechanism only underneath the "GSSAPI" SASL
198 Since SASL is capable of negotiating amongst GSSAPI mechanisms, the
199 only reason for a server or client to support the "GSS-SPNEGO"
200 mechanism is to allow a policy of only using mechanisms below a
201 certain strength if those mechanism's negotiation is protected. In
202 such a case, a client or server would only want to negotiate those
203 weaker mechanisms through SPNEGO. In any case, there is no down-
204 negotiation security consideration with using the strongest mechanism
205 and set of options the implementation supports, so for
206 interoperability that mechanism and set of options MUST be negotiable
207 without using the "GSS-SPNEGO" mechanism.
209 If a client's policy is to first prefer GSSAPI mechanism X, then
210 non-GSSAPI mechanism Y, then GSSAPI mechanism Z, and if a server
211 supports mechanisms Y and Z but not X, then if the client attempts to
212 negotiate mechanism X by using the "GSS-SPNEGO" SASL mechanism, it
213 may end up using mechanism Z when it should have used mechanism Y.
214 For this reason, implementations MUST exclude from SPNEGO those
215 GSSAPI mechanisms which are weaker than the strongest non-GSSAPI SASL
216 mechanism advertised by the server.
220 The Base32 encoding is designed to represent arbitrary sequences of
221 octets in a form that needs to be case insensitive but need not be
228 Internet DRAFT GSSAPI SASL mechanisms May 30, 2001
231 A 33-character subset of US-ASCII is used, enabling 5 bits to be
232 represented per printable character. (The extra 33rd character, "=",
233 is used to signify a special processing function.)
235 The encoding process represents 40-bit groups of input bits as output
236 strings of 8 encoded characters. Proceeding from left to right, a
237 40-bit input group is formed by concatenating 5 8bit input groups.
238 These 40 bits are then treated as 8 concatenated 5-bit groups, each
239 of which is translated into a single digit in the base32 alphabet.
240 When encoding a bit stream via the base32 encoding, the bit stream
241 must be presumed to be ordered with the most-significant-bit first.
242 That is, the first bit in the stream will be the high-order bit in
243 the first 8bit byte, and the eighth bit will be the low-order bit in
244 the first 8bit byte, and so on.
246 Each 5-bit group is used as an index into an array of 32 printable
247 characters. The character referenced by the index is placed in the
248 output string. These characters, identified in Table 1, below, are
249 selected from US-ASCII digits and uppercase letters.
251 Table 1: The Base32 Alphabet
253 Value Encoding Value Encoding Value Encoding Value Encoding
260 6 G 15 P 24 Y (pad) =
264 Special processing is performed if fewer than 40 bits are available
265 at the end of the data being encoded. A full encoding quantum is
266 always completed at the end of a body. When fewer than 40 input bits
267 are available in an input group, zero bits are added (on the right)
268 to form an integral number of 5-bit groups. Padding at the end of
269 the data is performed using the "=" character. Since all base32
270 input is an integral number of octets, only the following cases can
271 arise: (1) the final quantum of encoding input is an integral
272 multiple of 40 bits; here, the final unit of encoded output will be
273 an integral multiple of 8 characters with no "=" padding, (2) the
274 final quantum of encoding input is exactly 8 bits; here, the final
275 unit of encoded output will be two characters followed by six "="
276 padding characters, (3) the final quantum of encoding input is
277 exactly 16 bits; here, the final unit of encoded output will be four
278 characters followed by four "=" padding characters, (4) the final
284 Internet DRAFT GSSAPI SASL mechanisms May 30, 2001
287 quantum of encoding input is exactly 24 bits; here, the final unit of
288 encoded output will be five characters followed by three "=" padding
289 characters, or (5) the final quantum of encoding input is exactly 32
290 bits; here, the final unit of encoded output will be seven characters
291 followed by one "=" padding character.
293 Because it is used only for padding at the end of the data, the
294 occurrence of any "=" characters may be taken as evidence that the
295 end of the data has been reached (without truncation in transit). No
296 such assurance is possible, however, when the number of octets
297 transmitted was a multiple of 8 and no "=" characters are present.
299 Any characters outside of the base32 alphabet are to be ignored in
302 6. Specification common to all GSSAPI mechanisms
304 Each SASL mechanism which uses a GSSAPI mechanism uses the following
307 The implementation MAY set any GSSAPI flags or arguments not
308 mentioned in this specification as is necessary for the
309 implementation to enforce its security policy.
311 6.1. Client side of authentication protocol exchange
313 The client calls GSS_Init_sec_context, passing in
314 input_context_handle of 0 (initially), mech_type of the GSSAPI
315 mechanism for which this SASL mechanism is registered, chan_binding
316 of NULL, and targ_name equal to output_name from GSS_Import_Name
317 called with input_name_type of GSS_C_NT_HOSTBASED_SERVICE and
318 input_name_string of "service@hostname" where "service" is the
319 service name specified in the protocol's profile, and "hostname" is
320 the fully qualified host name of the server. If the client will be
321 requesting a security layer, it MUST also supply to the
322 GSS_Init_sec_context a mutual_req_flag of TRUE, a sequence_req_flag
323 of TRUE, and an integ_req_flag of TRUE. If the client will be
324 requesting a security layer providing confidentiality protection, it
325 MUST also supply to the GSS_Init_sec_context a conf_req_flag of TRUE.
326 The client then responds with the resulting output_token. If
327 GSS_Init_sec_context returns GSS_S_CONTINUE_NEEDED, then the client
328 should expect the server to issue a token in a subsequent challenge.
329 The client must pass the token to another call to
330 GSS_Init_sec_context, repeating the actions in this paragraph.
332 When GSS_Init_sec_context returns GSS_S_COMPLETE, the client examines
333 the context to ensure that it provides a level of protection
334 permitted by the client's security policy. If the context is
340 Internet DRAFT GSSAPI SASL mechanisms May 30, 2001
343 acceptable, the client takes the following actions: If the last call
344 to GSS_Init_sec_context returned an output_token, then the client
345 responds with the output_token, otherwise the client responds with no
346 data. The client should then expect the server to issue a token in a
347 subsequent challenge. The client passes this token to GSS_Unwrap and
348 interprets the first octet of resulting cleartext as a bit-mask
349 specifying the security layers supported by the server and the second
350 through fourth octets as the network byte order maximum size
351 output_message to send to the server (if the resulting cleartext is
352 not 4 octets long, the client fails the negotiation). The client
353 then constructs data, with the first octet containing the bit-mask
354 specifying the selected security layer, the second through fourth
355 octets containing in network byte order the maximum size
356 output_message the client is able to receive, and the remaining
357 octets containing the UTF-8 encoded [UTF8] authorization identity.
358 The authorization identity is not NUL-terminated. The client passes
359 the data to GSS_Wrap with conf_flag set to FALSE, and responds with
360 the generated output_message. The client can then consider the
361 server authenticated.
363 6.2. Server side of authentication protocol exchange
365 The server passes the initial client response to
366 GSS_Accept_sec_context as input_token, setting input_context_handle
367 to 0 (initially), mech_type of the GSSAPI mechanism for which this
368 SASL mechanism is registered, chan_binding of NULL, and
369 acceptor_cred_handle equal to output_cred_handle from
370 GSS_Acquire_cred called with desired_name equal to output_name from
371 GSS_Import_name with input_name_type of GSS_C_NT_HOSTBASED_SERVICE
372 and input_name_string of "service@hostname" where "service" is the
373 service name specified in the protocol's profile, and "hostname" is
374 the fully qualified host name of the server. If
375 GSS_Accept_sec_context returns GSS_S_CONTINUE_NEEDED, the server
376 returns the generated output_token to the client in challenge and
377 passes the resulting response to another call to
378 GSS_Accept_sec_context, repeating the actions in this paragraph.
380 When GSS_Accept_sec_context returns GSS_S_COMPLETE, the server
381 examines the context to ensure that it provides a level of protection
382 permitted by the server's security policy. If the context is
383 acceptable, the server takes the following actions: If the last call
384 to GSS_Accept_sec_context returned an output_token, the server
385 returns it to the client in a challenge and expects a reply from the
386 client with no data. Whether or not an output_token was returned
387 (and after receipt of any response from the client to such an
388 output_token), the server then constructs 4 octets of data, with the
389 first octet containing a bit-mask specifying the security layers
390 supported by the server and the second through fourth octets
396 Internet DRAFT GSSAPI SASL mechanisms May 30, 2001
399 containing in network byte order the maximum size output_token the
400 server is able to receive. The server must then pass the plaintext
401 to GSS_Wrap with conf_flag set to FALSE and issue the generated
402 output_message to the client in a challenge. The server must then
403 pass the resulting response to GSS_Unwrap and interpret the first
404 octet of resulting cleartext as the bit-mask for the selected
405 security layer, the second through fourth octets as the network byte
406 order maximum size output_message to send to the client, and the
407 remaining octets as the authorization identity. The server must
408 verify that the src_name is authorized to authenticate as the
409 authorization identity. After these verifications, the
410 authentication process is complete.
414 The security layers and their corresponding bit-masks are as follows:
417 2 Integrity protection.
418 Sender calls GSS_Wrap with conf_flag set to FALSE
419 4 Confidentiality protection.
420 Sender calls GSS_Wrap with conf_flag set to TRUE
422 Other bit-masks may be defined in the future; bits which are not
423 understood must be negotiated off.
425 Note that SASL negotiates the maximum size of the output_message to
426 send. Implementations can use the GSS_Wrap_size_limit call to
427 determine the corresponding maximum size input_message.
429 7. IANA Considerations
431 The IANA is advised that SASL mechanism names starting with "GSS-"
432 are reserved for SASL mechanisms which conform to this document. The
433 IANA is directed to place a statement to that effect in the sasl-
436 The IANA is directed to modify the existing registration for "GSSAPI"
437 in the "sasl-mechanisms" so that RFC [THIS-DOC] is listed as the
438 published specification. Add the descriptive text "This mechanism is
439 for the Kerberos V5 mechanism of GSSAPI. Other GSSAPI mechanisms use
440 other SASL mechanism names, as described in this mechanism's
441 published specification."
443 The IANA is directed to modify the existing registration for "GSS-
446 SASL mechanism name: GSS-SPNEGO
452 Internet DRAFT GSSAPI SASL mechanisms May 30, 2001
455 Security considerations: See the "SPNEGO" section of RFC [THIS-DOC].
457 Published Specification: RFC [THIS-DOC]
459 Intended usage: LIMITED USE
461 Author/Change controller: iesg@ietf.org
508 Internet DRAFT GSSAPI SASL mechanisms May 30, 2001
513 [ASN1] ISO/IEC 8824, "Specification of Abstract Syntax Notation One
516 [GSSAPI] Linn, J., "Generic Security Service Application Program
517 Interface Version 2, Update 1", RFC 2743, January 2000
519 [GSSAPI-KERBEROS] Linn, J., "The Kerberos Version 5 GSS-API
520 Mechanism", RFC 1964, June 1996
522 [IMAP4] Crispin, M., "Internet Message Access Protocol - Version 4",
523 RFC 1730, University of Washington, December 1994.
525 [KEYWORDS] Bradner, "Key words for use in RFCs to Indicate
526 Requirement Levels", RFC 2119, March 1997
528 [MD5] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, April
531 [SASL] Myers, J., "Simple Authentication and Security Layer (SASL)",
532 RFC 2222, October 1997
534 [SPKM] Adams, C., "The Simple Public-Key GSS-API Mechanism (SPKM)",
535 RFC 2025, October 1996
537 [SPNEGO] Baize, E., Pinkas., D., "The Simple and Protected GSS-API
538 Negotiation Mechanism", RFC 2478, December 1998
540 [UTF8] Yergeau, F., "UTF-8, a transformation format of ISO 10646",
541 RFC 2279, January 1998
543 9. Security Considerations
545 Security issues are discussed throughout this memo.
547 When a server or client supports multiple authentication mechanisms,
548 each of which has a different security strength, it is possible for
549 an active attacker to cause a party to use the least secure mechanism
550 supported. To protect against this sort of attack, a client or
551 server which supports mechanisms of different strengths should have a
552 configurable minimum strength that it will use. It is not sufficient
553 for this minimum strength check to only be on the server, since an
554 active attacker can change which mechanisms the client sees as being
555 supported, causing the client to send authentication credentials for
556 its weakest supported mechanism.
558 The client's selection of a SASL mechanism is done in the clear and
564 Internet DRAFT GSSAPI SASL mechanisms May 30, 2001
567 may be modified by an active attacker. It is important for any new
568 SASL mechanisms to be designed such that an active attacker cannot
569 obtain an authentication with weaker security properties by modifying
570 the SASL mechanism name and/or the challenges and responses.
572 SPNEGO [SPNEGO] has protection against many of these down-negotiation
573 attacks, SASL does not itself have such protection. The section
574 titled "SPNEGO" mentions considerations of choosing negotiation
575 through SASL versus SPNEGO.
577 The integrity protection provided by the security layer is useless to
578 the client unless the client also requests mutual authentication.
579 Therefore, a client wishing to benefit from the integrity protection
580 of a security layer MUST pass to the GSS_Init_sec_context call a
581 mutual_req_flag of TRUE.
583 Additional security considerations are in the SASL [SASL] and GSSAPI
584 [GSSAPI] specifications.
589 Netscape Communications
590 501 E. Middlefield Road
592 Mountain View, CA 94043-4042
594 Email: jgmyers@netscape.com
620 Internet DRAFT GSSAPI SASL mechanisms May 30, 2001
623 Appendix A. Sample code
625 The following is an example program which converts mechanism OIDs (of
626 the form "1.3.6.1.5.5.1") to SASL mechanism names. This sample
627 program uses the reference MD5 implementation in [MD5].
634 const unsigned char oid[15];
635 const char *saslname;
637 { { 0x06, 0x05, 0x2b, 0x05, 0x01, 0x05, 0x02 }, "GSSAPI" },
638 { { 0x06, 0x09, 0x2a, 0x86, 0x48, 0x86, 0xf7, 0x12, 0x01, 0x02, 0x02 },
639 "GSSAPI" }, /* old Kerberos V5 OID */
640 { { 0x06, 0x06, 0x2b, 0x06, 0x01, 0x05, 0x05, 0x02 }, "GSS-SPNEGO" },
643 static unsigned long parsenum(char **ptr)
645 unsigned long rval = 0;
646 while (**ptr >= '0' && **ptr <= '9') {
647 rval = rval * 10 + *(*ptr)++ - '0';
652 static void asn1encode(unsigned long val, unsigned char **buf)
654 unsigned long tmpval;
656 for (tmpval = val; tmpval >= 128; tmpval >>= 7) noctets++;
658 *(*buf)++ = ((val >> (7 * noctets)) & 0x7f) | 0x80;
660 *(*buf)++ = val & 0x7f;
663 static char basis_32[] = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
666 * Convert the GSSAPI mechanism 'oid' of length 'oidlen', placing
667 * the result into 'retbuf', which must be of size 21
669 void oidToSaslMech(const unsigned char *oid, unsigned oidlen, char *retbuf)
676 Internet DRAFT GSSAPI SASL mechanisms May 30, 2001
681 unsigned char md5buf[16];
687 /* See if it has a backwards-compatibility SASL mechanism name */
688 for (i = 0; i < (sizeof(compat_map) / sizeof(compat_map[0])); i++) {
689 if (memcmp(compat_map[i].oid, oid, oidlen) == 0) {
690 strcpy(retbuf, compat_map[i].saslname);
696 MD5Update(&md5ctx, (unsigned char *)oid, oidlen);
697 MD5Final(md5buf, &md5ctx);
699 printf("MD5 hash: ");
700 for (p = md5buf; p < md5buf + 16; p++) {
706 strcpy(retbuf, "GSS-");
707 out = retbuf + strlen(retbuf);
710 *out++ = basis_32[in[0] >> 3];
711 *out++ = basis_32[((in[0] & 7) << 2) | (in[1] >> 6)];
712 *out++ = basis_32[(in[1] & 0x3f) >> 1];
713 *out++ = basis_32[((in[1] & 1) << 4) | (in[2] >> 4)];
714 *out++ = basis_32[((in[2] & 0xf) << 1) | (in[3] >> 7)];
715 *out++ = basis_32[(in[3] & 0x7f) >> 2];
716 *out++ = basis_32[((in[3] & 3) << 3) | (in[4] >> 5)];
717 *out++ = basis_32[(in[4] & 0x1f)];
724 main(int argc, char **argv)
732 Internet DRAFT GSSAPI SASL mechanisms May 30, 2001
735 unsigned long val1, val2;
736 unsigned char asn1buf[1024];
737 unsigned char *asn1start = asn1buf + 4;
738 unsigned char *asn1next = asn1start;
739 unsigned char *asn1lennext;
742 unsigned char md5buf[16];
743 char saslmechbuf[21];
747 fprintf(stderr, "usage: %s oid\n", argv[0]);
752 val1 = parsenum(&oidstr);
753 if (*oidstr++ != '.') goto badoid;
754 val2 = parsenum(&oidstr);
755 if (*oidstr && *oidstr++ != '.') goto badoid;
756 *asn1next++ = val1 * 40 + val2;
759 val1 = parsenum(&oidstr);
760 if (*oidstr && *oidstr++ != '.') goto badoid;
762 asn1encode(val1, &asn1next);
765 /* Now that we know the length of the OID, generate the tag
768 asn1lennext = asn1next;
770 asn1encode(asn1next - asn1start, &asn1lennext);
772 /* Copy tag and length to beginning */
773 memcpy(asn1start - (asn1lennext - asn1next), asn1next,
774 asn1lennext - asn1next);
775 asn1start -= asn1lennext - asn1next;
777 printf("ASN.1 DER encoding: ");
778 for (p = asn1start; p < asn1next; p++) {
788 Internet DRAFT GSSAPI SASL mechanisms May 30, 2001
791 oidToSaslMech(asn1start, asn1next - asn1start, saslmechbuf);
792 printf("SASL mechanism name: %s\n", saslmechbuf);
797 fprintf(stderr, "bad oid syntax\n");