Doc fix.
[gsasl.git] / doc / specification / draft-ietf-sasl-gssapi-01.txt
blob3bb026d5e9e9aa228e186e220f4c669fd8648fa8
2 SASL Working Group                                           A. Melnikov
3 Internet-Draft                                                     Isode
4 Expires: December 24, 2004                                 June 25, 2004
7                          SASL GSSAPI mechanisms
8                        draft-ietf-sasl-gssapi-01
10 Status of this Memo
12    This document is an Internet-Draft and is in full conformance with
13    all provisions of Section 10 of RFC2026.
15    Internet-Drafts are working documents of the Internet Engineering
16    Task Force (IETF), its areas, and its working groups.  Note that
17    other groups may also distribute working documents as Internet-
18    Drafts.
20    Internet-Drafts are draft documents valid for a maximum of six months
21    and may be updated, replaced, or obsoleted by other documents at any
22    time.  It is inappropriate to use Internet-Drafts as reference
23    material or to cite them other than as "work in progress."
25    The list of current Internet-Drafts can be accessed at http://
26    www.ietf.org/ietf/1id-abstracts.txt.
28    The list of Internet-Draft Shadow Directories can be accessed at
29    http://www.ietf.org/shadow.html.
31    This Internet-Draft will expire on December 24, 2004.
33 Copyright Notice
35    Copyright (C) The Internet Society (2004).  All Rights Reserved.
37 Abstract
39    The Simple Authentication and Security Layer [SASL] is a method for
40    adding authentication support to connection-based protocols.  This
41    document describes the method for using the Generic Security Service
42    Application Program Interface [GSSAPI] in the Simple Authentication
43    and Security Layer [SASL].
45    This document replaces section 7.2 of RFC 2222 [SASL], the definition
46    of the "GSSAPI" SASL mechanism.
54 Melnikov                Expires December 24, 2004               [Page 1]
56 Internet-Draft           SASL GSSAPI mechanisms                June 2004
59 Table of Contents
61    1.  Conventions Used in this Document  . . . . . . . . . . . . . .  3
62    2.  Introduction and Overview  . . . . . . . . . . . . . . . . . .  4
63    2.1 Example  . . . . . . . . . . . . . . . . . . . . . . . . . . .  4
64    3.  SPNEGO . . . . . . . . . . . . . . . . . . . . . . . . . . . .  5
65    4.  Specification common to all GSSAPI mechanisms  . . . . . . . .  6
66    4.1 Client side of authentication protocol exchange  . . . . . . .  6
67    4.2 Server side of authentication protocol exchange  . . . . . . .  7
68    4.3 Security layer . . . . . . . . . . . . . . . . . . . . . . . .  8
69    5.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . .  9
70    6.  Security Considerations  . . . . . . . . . . . . . . . . . . . 11
71    7.  Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 12
72        Normative References . . . . . . . . . . . . . . . . . . . . . 13
73        Informative References . . . . . . . . . . . . . . . . . . . . 14
74        Author's Address . . . . . . . . . . . . . . . . . . . . . . . 14
75        Full Copyright Statement . . . . . . . . . . . . . . . . . . . 15
110 Melnikov                Expires December 24, 2004               [Page 2]
112 Internet-Draft           SASL GSSAPI mechanisms                June 2004
115 1. Conventions Used in this Document
117    The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY"
118    in this document are to be interpreted as defined in "Key words for
119    use in RFCs to Indicate Requirement Levels" [KEYWORDS].
166 Melnikov                Expires December 24, 2004               [Page 3]
168 Internet-Draft           SASL GSSAPI mechanisms                June 2004
171 2. Introduction and Overview
173    Each and every GSSAPI mechanism used within SASL is implicitly
174    registered by this specification.
176    For backwards compatibility with existing implementations of Kerberos
177    V5 and SPNEGO under SASL, the SASL mechanism name for the Kerberos V5
178    GSSAPI mechanism [KRB5GSS] is "GSSAPI" and the SASL mechanism for the
179    SPNEGO GSSAPI mechanism [SPNEGO] is "GSS-SPNEGO".  The SASL mechanism
180    name for any other GSSAPI mechanism is the concatenation of "GSS-"
181    and the Base32 [BASE-ENCODING] encoding of the first ten bytes of the
182    MD5 hash [MD5] of the ASN.1 DER encoding [ASN1] of the GSSAPI
183    mechanism's OID.  The Base32 rules on padding characters and
184    characters outside of the base32 alphabet are not relevant to this
185    use of Base32.
187    SASL mechanism names starting with "GSS-" are reserved for SASL
188    mechanisms which conform to this document.
190    The specification of all SASL mechanisms conforming to this document
191    is in the "Specification common to all GSSAPI mechanisms" section of
192    this document.
194    The IESG is considered to be the owner of all SASL mechanisms which
195    conform to this document.  This does NOT necessarily imply that the
196    IESG is considered to be the owner of the underlying GSSAPI
197    mechanism.
199 2.1 Example
201    The OID for the SPKM-1 mechanism [SPKM1] is 1.3.6.1.5.5.1.  The ASN.1
202    DER encoding of this OID is 06 06 2b 06 01 05 05 01.  The MD5 hash of
203    the ASN.1 DER encoding is 57 ee 81 82 4e ac 4d b0 e6 50 9f 60 1f 46
204    8a 30.  The Base32 encoding of the first ten bytes of this is
205    "K7XIDASOVRG3BZSQ".  Thus the SASL mechanism name for the SPKM-1
206    GSSAPI mechanism is "GSS-K7XIDASOVRG3BZSQ".
222 Melnikov                Expires December 24, 2004               [Page 4]
224 Internet-Draft           SASL GSSAPI mechanisms                June 2004
227 3. SPNEGO
229    Use of the Simple and Protected GSS-API Negotiation Mechanism
230    [SPNEGO] underneath SASL introduces subtle interoperability problems
231    and security considerations.  To address these, this section places
232    additional requirements on implementations which support SPNEGO
233    underneath SASL.
235    A client which supports, for example, the Kerberos V5 GSSAPI
236    mechanism only underneath SPNEGO underneath the "GSS-SPNEGO" SASL
237    mechanism will not interoperate with a server which supports the
238    Kerberos V5 GSSAPI mechanism only underneath the "GSSAPI" SASL
239    mechanism.
241    Since SASL is capable of negotiating amongst GSSAPI mechanisms, the
242    only reason for a server or client to support the "GSS-SPNEGO"
243    mechanism is to allow a policy of only using mechanisms below a
244    certain strength if those mechanism's negotiation is protected.  In
245    such a case, a client or server would only want to negotiate those
246    weaker mechanisms through SPNEGO.  In any case, there is no down-
247    negotiation security consideration with using the strongest mechanism
248    and set of options the implementation supports, so for
249    interoperability that mechanism and set of options MUST be negotiable
250    without using the "GSS-SPNEGO" mechanism.
252    If a client's policy is to first prefer GSSAPI mechanism X, then non-
253    GSSAPI mechanism Y, then GSSAPI mechanism Z, and if a server supports
254    mechanisms Y and Z but not X, then if the client attempts to
255    negotiate mechanism X by using the "GSS-SPNEGO" SASL mechanism, it
256    may end up using mechanism Z when it should have used mechanism Y.
257    For this reason, implementations MUST exclude from SPNEGO those
258    GSSAPI mechanisms which are weaker than the strongest non-GSSAPI SASL
259    mechanism advertised by the server.
278 Melnikov                Expires December 24, 2004               [Page 5]
280 Internet-Draft           SASL GSSAPI mechanisms                June 2004
283 4. Specification common to all GSSAPI mechanisms
285    Each SASL mechanism which uses a GSSAPI mechanism uses the following
286    specification.
288    The implementation MAY set any GSSAPI flags or arguments not
289    mentioned in this specification as is necessary for the
290    implementation to enforce its security policy.
292 4.1 Client side of authentication protocol exchange
294    The client calls GSS_Init_sec_context, passing in
295    input_context_handle of 0 (initially), mech_type of the GSSAPI
296    mechanism for which this SASL mechanism is registered, chan_binding
297    of NULL, and targ_name equal to output_name from GSS_Import_Name
298    called with input_name_type of GSS_C_NT_HOSTBASED_SERVICE and
299    input_name_string of "service@hostname" where "service" is the
300    service name specified in the protocol's profile, and "hostname" is
301    the fully qualified host name of the server.  If the client will be
302    requesting a security layer, it MUST also supply to the
303    GSS_Init_sec_context a mutual_req_flag of TRUE, a sequence_req_flag
304    of TRUE, and an integ_req_flag of TRUE.  If the client will be
305    requesting a security layer providing confidentiality protection, it
306    MUST also supply to the GSS_Init_sec_context a conf_req_flag of TRUE.
307    The client then responds with the resulting output_token.  If
308    GSS_Init_sec_context returns GSS_S_CONTINUE_NEEDED, then the client
309    should expect the server to issue a token in a subsequent challenge.
310    The client must pass the token to another call to
311    GSS_Init_sec_context, repeating the actions in this paragraph.
313    When GSS_Init_sec_context returns GSS_S_COMPLETE, the client examines
314    the context to ensure that it provides a level of protection
315    permitted by the client's security policy.  If the context is
316    acceptable, the client takes the following actions: If the last call
317    to GSS_Init_sec_context returned an output_token, then the client
318    responds with the output_token, otherwise the client responds with no
319    data.  The client should then expect the server to issue a token in a
320    subsequent challenge.  The client passes this token to GSS_Unwrap and
321    interprets the first octet of resulting cleartext as a bit-mask
322    specifying the security layers supported by the server and the second
323    through fourth octets as the network byte order maximum size
324    output_message to send to the server (if the resulting cleartext is
325    not 4 octets long, the client fails the negotiation).  The client
326    then constructs data, with the first octet containing the bit-mask
327    specifying the selected security layer, the second through fourth
328    octets containing in network byte order the maximum size
329    output_message the client is able to receive, and the remaining
330    octets containing the UTF-8 [UTF8] encoded authorization identity.
334 Melnikov                Expires December 24, 2004               [Page 6]
336 Internet-Draft           SASL GSSAPI mechanisms                June 2004
339    (Implementation note: the authorization identity is not terminated
340    with the NUL (%x00) character).  The client passes the data to
341    GSS_Wrap with conf_flag set to FALSE, and responds with the generated
342    output_message.  The client can then consider the server
343    authenticated.
345 4.2 Server side of authentication protocol exchange
347    The server passes the initial client response to
348    GSS_Accept_sec_context as input_token, setting input_context_handle
349    to 0 (initially), mech_type of the GSSAPI mechanism for which this
350    SASL mechanism is registered, chan_binding of NULL, and
351    acceptor_cred_handle equal to output_cred_handle from
352    GSS_Acquire_cred called with desired_name equal to output_name from
353    GSS_Import_name with input_name_type of GSS_C_NT_HOSTBASED_SERVICE
354    and input_name_string of "service@hostname" where "service" is the
355    service name specified in the protocol's profile, and "hostname" is
356    the fully qualified host name of the server.  If
357    GSS_Accept_sec_context returns GSS_S_CONTINUE_NEEDED, the server
358    returns the generated output_token to the client in challenge and
359    passes the resulting response to another call to
360    GSS_Accept_sec_context, repeating the actions in this paragraph.
362    When GSS_Accept_sec_context returns GSS_S_COMPLETE, the server
363    examines the context to ensure that it provides a level of protection
364    permitted by the server's security policy.  If the context is
365    acceptable, the server takes the following actions: If the last call
366    to GSS_Accept_sec_context returned an output_token, the server
367    returns it to the client in a challenge and expects a reply from the
368    client with no data.  Whether or not an output_token was returned
369    (and after receipt of any response from the client to such an
370    output_token), the server then constructs 4 octets of data, with the
371    first octet containing a bit-mask specifying the security layers
372    supported by the server and the second through fourth octets
373    containing in network byte order the maximum size output_token the
374    server is able to receive.  The server must then pass the plaintext
375    to GSS_Wrap with conf_flag set to FALSE and issue the generated
376    output_message to the client in a challenge.  The server must then
377    pass the resulting response to GSS_Unwrap and interpret the first
378    octet of resulting cleartext as the bit-mask for the selected
379    security layer, the second through fourth octets as the network byte
380    order maximum size output_message to send to the client, and the
381    remaining octets as the authorization identity.  The server must
382    verify that the src_name is authorized to authenticate as the
383    authorization identity.  After these verifications, the
384    authentication process is complete.
390 Melnikov                Expires December 24, 2004               [Page 7]
392 Internet-Draft           SASL GSSAPI mechanisms                June 2004
395 4.3 Security layer
397    The security layers and their corresponding bit-masks are as follows:
399          1 No security layer
400          2 Integrity protection.
401            Sender calls GSS_Wrap with conf_flag set to FALSE
402          4 Confidentiality protection.
403            Sender calls GSS_Wrap with conf_flag set to TRUE
405    Other bit-masks may be defined in the future; bits which are not
406    understood must be negotiated off.
408    Note that SASL negotiates the maximum size of the output_message to
409    send.  Implementations can use the GSS_Wrap_size_limit call to
410    determine the corresponding maximum size input_message.
446 Melnikov                Expires December 24, 2004               [Page 8]
448 Internet-Draft           SASL GSSAPI mechanisms                June 2004
451 5. IANA Considerations
453    The IANA is advised that SASL mechanism names starting with "GSS-"
454    are reserved for SASL mechanisms which conform to this document.  The
455    IANA is directed to place a statement to that effect in the sasl-
456    mechanisms registry.
458    Family of SASL mechanisms: YES
460    Prefix: GSS-
462    Security considerations: RFC [THIS-DOC]
464    Published Specification: RFC [THIS-DOC]
466    Person & email address to contact for further information: Alexey
467       Melnikov <Alexey.Melnikov@isode.com>
469    Intended usage: COMMON
471    Owner/Change controller: iesg@ietf.org
474    The IANA is directed to modify the existing registration for "GSSAPI"
475    as follows:
477    Family of SASL mechanisms: NO
479    SASL mechanism name: GSSAPI
481    Security considerations: ?
483    Published Specification: RFC [THIS-DOC]
485    Person & email address to contact for further information: Alexey
486       Melnikov <Alexey.Melnikov@isode.com>
488    Intended usage: COMMON
490    Owner/Change controller: iesg@ietf.org
492    Additional Information: This mechanism is for the Kerberos V5
493       mechanism of GSSAPI.  Other GSSAPI mechanisms use other SASL
494       mechanism names, as described in this mechanism's published
495       specification.
498    The IANA is directed to modify the existing registration for "GSS-
502 Melnikov                Expires December 24, 2004               [Page 9]
504 Internet-Draft           SASL GSSAPI mechanisms                June 2004
507    SPNEGO" as follows:
509    Family of SASL mechanisms: NO
511    SASL mechanism name: GSS-SPNEGO
513    Security considerations: See the "SPNEGO" section of RFC [THIS-DOC].
515    Published Specification: RFC [THIS-DOC]
517    Person & email address to contact for further information: Alexey
518       Melnikov <Alexey.Melnikov@isode.com>
520    Intended usage: LIMITED USE
522    Owner/Change controller: iesg@ietf.org
558 Melnikov                Expires December 24, 2004              [Page 10]
560 Internet-Draft           SASL GSSAPI mechanisms                June 2004
563 6. Security Considerations
565    Security issues are discussed throughout this memo.
567    When a server or client supports multiple authentication mechanisms,
568    each of which has a different security strength, it is possible for
569    an active attacker to cause a party to use the least secure mechanism
570    supported.  To protect against this sort of attack, a client or
571    server which supports mechanisms of different strengths should have a
572    configurable minimum strength that it will use.  It is not sufficient
573    for this minimum strength check to only be on the server, since an
574    active attacker can change which mechanisms the client sees as being
575    supported, causing the client to send authentication credentials for
576    its weakest supported mechanism.
578    The client's selection of a SASL mechanism is done in the clear and
579    may be modified by an active attacker.  It is important for any new
580    SASL mechanisms to be designed such that an active attacker cannot
581    obtain an authentication with weaker security properties by modifying
582    the SASL mechanism name and/or the challenges and responses.
584    [SPNEGO] has protection against many of these down-negotiation
585    attacks, SASL does not itself have such protection.  The section
586    titled "SPNEGO" mentions considerations of choosing negotiation
587    through SASL versus SPNEGO.
589    The integrity protection provided by the security layer is useless to
590    the client unless the client also requests mutual authentication.
591    Therefore, a client wishing to benefit from the integrity protection
592    of a security layer MUST pass to the GSS_Init_sec_context call a
593    mutual_req_flag of TRUE.
595    When constructing the input_name_string, the client should not
596    canonicalize the server's fully qualified domain name using an
597    insecure or untrusted directory service.
599    Additional security considerations are in the [SASL] and [GSSAPI]
600    specifications.  Additional security considerations for the GSSAPI
601    mechanism can be found in [KRB5GSS].
614 Melnikov                Expires December 24, 2004              [Page 11]
616 Internet-Draft           SASL GSSAPI mechanisms                June 2004
619 7. Acknowledgements
621    This document is a revision of RFC 2222 written by John G.  Myers.
622    He also contributed significantly to this revision.
624    Thank you to Lawrence Greenfield for converting text of this draft to
625    XML format.
627    Contributions of many members of the SASL mailing list are gratefully
628    acknowledged.
670 Melnikov                Expires December 24, 2004              [Page 12]
672 Internet-Draft           SASL GSSAPI mechanisms                June 2004
675 Normative References
677    [ASN1]           International Organization for Standardization,
678                     "Information Processing Systems - Open Systems
679                     Interconnection - Specification of Abstract Syntax
680                     Notation One (ASN.1)", ISO Standard 8824, December
681                     1990.
683    [BASE-ENCODING]  Josefsson, S., "The Base16, Base32, and Base64 Data
684                     Encodings", RFC 3548, July 2003.
686    [GSSAPI]         Linn, J., "Generic Security Service Application
687                     Program Interface Version 2, Update 1", RFC 2743,
688                     January 2000.
690    [KEYWORDS]       Bradner, S., "Key words for use in RFCs to Indicate
691                     Requirement Levels", BCP 14, RFC 2119, March 1997.
693    [KRB5GSS]        Linn, J., "The Kerberos Version 5 GSS-API
694                     Mechanism", RFC 1964, June 1996.
696    [MD5]            Rivest, R., "The MD5 Message-Digest Algorithm", RFC
697                     1321, April 1992.
699    [SASL]           Myers, J., "Simple Authentication and Security Layer
700                     (SASL)", RFC 2222, October 1997.
702    [SASL[2]]        Melnikov, A., "Simple Authentication and Security
703                     Layer (SASL)", draft-ietf-sasl-rfc2222bis (work in
704                     progress), June 2004.
706    [SPNEGO]         Baize, E. and D. Pinkas, "The Simple and Protected
707                     GSS-API Negotiation Mechanism", RFC 2478, December
708                     1998.
710    [UTF8]           Yergeau, F., "UTF-8, a transformation format of ISO
711                     10646", RFC 2279, January 1998.
726 Melnikov                Expires December 24, 2004              [Page 13]
728 Internet-Draft           SASL GSSAPI mechanisms                June 2004
731 Informative References
733    [SPKM1]  Adams, C., "The Simple Public-Key GSS-API Mechanism (SPKM)",
734             RFC 2025, October 1996.
737 Author's Address
739    Alexey Melnikov (Ed.)
740    Isode Limited
741    5 Castle Business Village
742    36 Station Road
743    Hampton, Middlesex  TW12 2BX
744    UK
746    EMail: Alexey.Melnikov@isode.com
747    URI:   http://www.melnikov.ca/
782 Melnikov                Expires December 24, 2004              [Page 14]
784 Internet-Draft           SASL GSSAPI mechanisms                June 2004
787 Full Copyright Statement
789    Copyright (C) The Internet Society (2004).  This document is subject
790    to the rights, licenses and restrictions contained in BCP 78, and
791    except as set forth therein, the authors retain all their rights.
793    This document and translations of it may be copied and furnished to
794    others, and derivative works that comment on or otherwise explain it
795    or assist in its implementation may be prepared, copied, published
796    and distributed, in whole or in part, without restriction of any
797    kind, provided that the above copyright notice and this paragraph are
798    included on all such copies and derivative works.  However, this
799    document itself may not be modified in any way, such as by removing
800    the copyright notice or references to the Internet Society or other
801    Internet organizations, except as needed for the purpose of
802    developing Internet standards in which case the procedures for
803    copyrights defined in the Internet Standards process must be
804    followed, or as required to translate it into languages other than
805    English.
807    The limited permissions granted above are perpetual and will not be
808    revoked by the Internet Society or its successors or assigns.
810    This document and the information contained herein are provided on an
811    "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
812    OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
813    ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
814    INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
815    INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
816    WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
818 Acknowledgement
820    Funding for the RFC Editor function is currently provided by the
821    Internet Society.
838 Melnikov                Expires December 24, 2004              [Page 15]