Doc fix.

[gsasl.git] / doc / specification / draft-ietf-sasl-gssapi-05.txt

SASL                                                         A. Melnikov
Internet-Draft                                                     Isode
Expires: December 1, 2006                                   May 30, 2006


               The Kerberos V5 ("GSSAPI") SASL mechanism
                       draft-ietf-sasl-gssapi-05

Status of this Memo

   By submitting this Internet-Draft, each author represents that any
   applicable patent or other IPR claims of which he or she is aware
   have been or will be disclosed, and any of which he or she becomes
   aware will be disclosed, in accordance with Section 6 of BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF), its areas, and its working groups.  Note that
   other groups may also distribute working documents as Internet-
   Drafts.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   The list of current Internet-Drafts can be accessed at
   http://www.ietf.org/ietf/1id-abstracts.txt.

   The list of Internet-Draft Shadow Directories can be accessed at
   http://www.ietf.org/shadow.html.

   This Internet-Draft will expire on December 1, 2006.

Copyright Notice

   Copyright (C) The Internet Society (2006).

Abstract

   The Simple Authentication and Security Layer (SASL, RFC XXXX) is a
   framework for adding authentication support to connection-based
   protocols.  This document describes the method for using the Generic
   Security Service Application Program Interface (GSS-API) KERBEROS V5
   in the Simple Authentication and Security Layer.

   This document replaces section 7.2 of RFC 2222, the definition of the
   "GSSAPI" SASL mechanism.




Melnikov                Expires December 1, 2006                [Page 1]
\f
Internet-Draft  The Kerberos V5 ("GSSAPI") SASL mechanism       May 2006


Table of Contents

   1.  Conventions Used in this Document  . . . . . . . . . . . . . .  3
   2.  Introduction and Overview  . . . . . . . . . . . . . . . . . .  3
   3.  Kerberos V5 GSS-API mechanism  . . . . . . . . . . . . . . . .  3
     3.1.  Client side of authentication protocol exchange  . . . . .  3
     3.2.  Server side of authentication protocol exchange  . . . . .  4
     3.3.  Security layer . . . . . . . . . . . . . . . . . . . . . .  6
   4.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . .  6
   5.  Security Considerations  . . . . . . . . . . . . . . . . . . .  7
   6.  Acknowledgements . . . . . . . . . . . . . . . . . . . . . . .  7
   7.  References . . . . . . . . . . . . . . . . . . . . . . . . . .  8
     7.1.  Normative References . . . . . . . . . . . . . . . . . . .  8
     7.2.  Informative References . . . . . . . . . . . . . . . . . .  8
   Author's Address . . . . . . . . . . . . . . . . . . . . . . . . .  9
   Intellectual Property and Copyright Statements . . . . . . . . . . 10



































Melnikov                Expires December 1, 2006                [Page 2]
\f
Internet-Draft  The Kerberos V5 ("GSSAPI") SASL mechanism       May 2006


1.  Conventions Used in this Document

   The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY"
   in this document are to be interpreted as defined in "Key words for
   use in RFCs to Indicate Requirement Levels" [KEYWORDS].


2.  Introduction and Overview

   This specification documents currently deployed Kerberos V5 GSS-API
   mechanism used within SASL framework [SASL].  The authentication
   sequence is described in Section 3.  Note that the described
   authentication sequence has known limitations in particular it lacks
   channel bindings and the number of round trips required to complete
   authentication exchange is not minimal.  SASL WG is working on a
   separate document that should address these limitations.

   The SASL mechanism name for the Kerberos V5 GSS-API mechanism
   [RFC4121] is "GSSAPI".


3.  Kerberos V5 GSS-API mechanism

   The GSSAPI SASL mechanism is a "client goes first" SASL mechanism,
   i.e. it starts with the client sending a "response" created as
   described in the following section.

   The implementation MAY set any GSS-API flags or arguments not
   mentioned in this specification as is necessary for the
   implementation to enforce its security policy.

3.1.  Client side of authentication protocol exchange

   The client calls GSS_Init_sec_context, passing in
   input_context_handle of 0 (initially), mech_type of the Kerberos V5
   GSS-API mechanism [KRB5GSS], chan_binding of NULL, and targ_name
   equal to output_name from GSS_Import_Name called with input_name_type
   of GSS_C_NT_HOSTBASED_SERVICE and input_name_string of
   "service@hostname" where "service" is the service name specified in
   the protocol's profile, and "hostname" is the fully qualified host
   name of the server.  If the client will be requesting a security
   layer, it MUST also supply to the GSS_Init_sec_context a
   mutual_req_flag of TRUE, a sequence_req_flag of TRUE, and an
   integ_req_flag of TRUE.  If the client will be requesting a security
   layer providing confidentiality protection, it MUST also supply to
   the GSS_Init_sec_context a conf_req_flag of TRUE.  The client then
   responds with the resulting output_token.  If GSS_Init_sec_context
   returns GSS_S_CONTINUE_NEEDED, then the client should expect the



Melnikov                Expires December 1, 2006                [Page 3]
\f
Internet-Draft  The Kerberos V5 ("GSSAPI") SASL mechanism       May 2006


   server to issue a token in a subsequent challenge.  The client must
   pass the token to another call to GSS_Init_sec_context, repeating the
   actions in this paragraph.

   When GSS_Init_sec_context returns GSS_S_COMPLETE, the client examines
   the context to ensure that it provides a level of protection
   permitted by the client's security policy.  If the context is
   acceptable, the client takes the following actions: If the last call
   to GSS_Init_sec_context returned an output_token, then the client
   responds with the output_token, otherwise the client responds with no
   data.  The client should then expect the server to issue a token in a
   subsequent challenge.  The client passes this token to GSS_Unwrap and
   interprets the first octet of resulting cleartext as a bit-mask
   specifying the security layers supported by the server and the second
   through fourth octets as the maximum size output_message the server
   is able to receive (in network byte order).  If the resulting
   cleartext is not 4 octets long, the client fails the negotiation.
   The client verifies that the server maximum buffer is 0 if the server
   doesn't advertise support for any security layer.  The client then
   constructs data, with the first octet containing the bit-mask
   specifying the selected security layer, the second through fourth
   octets containing in network byte order the maximum size
   output_message the client is able to receive (which MUST be 0 if the
   client doesn't support any security layer), and the remaining octets
   containing the UTF-8 [UTF8] encoded authorization identity.
   (Implementation note: the authorization identity is not terminated
   with the NUL (%x00) character).  The client passes the data to
   GSS_Wrap with conf_flag set to FALSE, and responds with the generated
   output_message.  The client can then consider the server
   authenticated.

3.2.  Server side of authentication protocol exchange

   A server MUST NOT advertise support for the "GSSAPI" SASL mechanism
   described in this document unless it has acceptor credential for the
   Kerberos V GSS-API Mechanism [KRB5GSS].

   The server passes the initial client response to
   GSS_Accept_sec_context as input_token, setting input_context_handle
   to 0 (initially), chan_binding of NULL, and a suitable
   acceptor_cred_handle (see below).  If GSS_Accept_sec_context returns
   GSS_S_CONTINUE_NEEDED, the server returns the generated output_token
   to the client in challenge and passes the resulting response to
   another call to GSS_Accept_sec_context, repeating the actions in this
   paragraph.

   Servers SHOULD use a credential obtained by calling GSS_Acquire_cred
   or GSS_Add_cred for the GSS_C_NO_NAME desired_name and the OID of the



Melnikov                Expires December 1, 2006                [Page 4]
\f
Internet-Draft  The Kerberos V5 ("GSSAPI") SASL mechanism       May 2006


   Kerberos V5 GSS-API mechanism [KRB5GSS](*).  Servers MAY use
   GSS_C_NO_CREDENTIAL as an acceptor credential handle.  Servers MAY
   use a credential obtained by calling GSS_Acquire_cred or GSS_Add_cred
   for the server's principal name(s) (**) and the Kerberos V5 GSS-API
   mechanism [KRB5GSS].

   (*) - Unlike GSS_Add_cred the GSS_Acquire_cred uses an OID set of
   GSS-API mechanism as an input parameter.  The OID set can be created
   by using GSS_Create_empty_OID_set and GSS_Add_OID_set_member.  It can
   be freed by calling the GSS_Release_oid_set.

   (**) - Use of server's principal names having
   GSS_C_NT_HOSTBASED_SERVICE name type and "service@hostname" format,
   where "service" is the service name specified in the protocol's
   profile, is RECOMMENDED.

   Upon successful establishment of the security context (i.e.
   GSS_Accept_sec_context returns GSS_S_COMPLETE) the server SHOULD
   verify that the negotiated GSS-API mechanism is indeed Kerberos V5
   [KRB5GSS].  This is done by examining the value of the mech_type
   parameter returned from the GSS_Accept_sec_context call.  If the
   value differ SASL authentication MUST be aborted.

   Upon successful establishment of the security context the server
   SHOULD also check using the GSS_Inquire_context that the target_name
   used by the client matches either:

   -  the GSS_C_NT_HOSTBASED_SERVICE "service@hostname" name syntax,
      where "service" is the service name specified in the application
      protocol's profile,

      or that

   -  the GSS_KRB5_NT_PRINCIPAL_NAME [KRB5GSS] name syntax for a two-
      component principal where the first component matches the service
      name specified in the application protocol's profile.

   When GSS_Accept_sec_context returns GSS_S_COMPLETE, the server
   examines the context to ensure that it provides a level of protection
   permitted by the server's security policy.  If the context is
   acceptable, the server takes the following actions: If the last call
   to GSS_Accept_sec_context returned an output_token, the server
   returns it to the client in a challenge and expects a reply from the
   client with no data.  Whether or not an output_token was returned
   (and after receipt of any response from the client to such an
   output_token), the server then constructs 4 octets of data, with the
   first octet containing a bit-mask specifying the security layers
   supported by the server and the second through fourth octets



Melnikov                Expires December 1, 2006                [Page 5]
\f
Internet-Draft  The Kerberos V5 ("GSSAPI") SASL mechanism       May 2006


   containing in network byte order the maximum size output_token the
   server is able to receive (which MUST be 0 if the server doesn't
   support any security layer).  The server must then pass the plaintext
   to GSS_Wrap with conf_flag set to FALSE and issue the generated
   output_message to the client in a challenge.  The server must then
   pass the resulting response to GSS_Unwrap and interpret the first
   octet of resulting cleartext as the bit-mask for the selected
   security layer, the second through fourth octets as the maximum size
   output_message the client is able to receive (in network byte order),
   and the remaining octets as the authorization identity.  The server
   verifies that the client has selected a security layer that was
   offered, and that the client maximum buffer is 0 if no security layer
   was chosen.  The server must verify that the src_name is authorized
   to act as the authorization identity.  After these verifications, the
   authentication process is complete.

3.3.  Security layer

   The security layers and their corresponding bit-masks are as follows:

         1 No security layer
         2 Integrity protection.
           Sender calls GSS_Wrap with conf_flag set to FALSE
         4 Confidentiality protection.
           Sender calls GSS_Wrap with conf_flag set to TRUE

   Other bit-masks may be defined in the future; bits which are not
   understood must be negotiated off.

   Note that SASL negotiates the maximum size of the output_message to
   send.  Implementations can use the GSS_Wrap_size_limit call to
   determine the corresponding maximum size input_message.


4.  IANA Considerations

   The IANA is directed to modify the existing registration for "GSSAPI"
   as follows:

   Family of SASL mechanisms: NO

   SASL mechanism name: GSSAPI

   Security considerations: See Section 5 of RFC [THIS-DOC]







Melnikov                Expires December 1, 2006                [Page 6]
\f
Internet-Draft  The Kerberos V5 ("GSSAPI") SASL mechanism       May 2006


   Published Specification: RFC [THIS-DOC]

   Person & email address to contact for further information: Alexey
      Melnikov <Alexey.Melnikov@isode.com>

   Intended usage: COMMON

   Owner/Change controller: iesg@ietf.org

   Additional Information: This mechanism is for the Kerberos V5
      mechanism of GSS-API.


5.  Security Considerations

   Security issues are discussed throughout this memo.

   The integrity protection provided by the GSSAPI security layer is
   useless to the client unless the client also requests mutual
   authentication.  Therefore, a client wishing to benefit from the
   integrity protection of a security layer MUST pass to the
   GSS_Init_sec_context call a mutual_req_flag of TRUE.

   When constructing the input_name_string, the client SHOULD NOT
   canonicalize the server's fully qualified domain name using an
   insecure or untrusted directory service.

   For compatibility with deployed software this document requires that
   the chan_binding (channel bindings) parameter to GSS_Init_sec_context
   and GSS_Accept_sec_context be NULL.  SASL WG has reached consensus
   that this limitation is worth addressing and a future document will
   define a new GSS-API SASL mechanism that will not have this
   limitation.

   Additional security considerations are in the [SASL] and [GSS-API]
   specifications.  Additional security considerations for the GSSAPI
   mechanism can be found in [KRB5GSS].


6.  Acknowledgements

   This document replaces section 7.2 of RFC 2222 [SASL] by John G.
   Myers.  He also contributed significantly to this revision.

   Thank you to Lawrence Greenfield for converting text of this draft to
   XML format.

   Contributions of many members of the SASL mailing list are gratefully



Melnikov                Expires December 1, 2006                [Page 7]
\f
Internet-Draft  The Kerberos V5 ("GSSAPI") SASL mechanism       May 2006


   acknowledged, in particular comments from Chris Newman, Nicolas
   Williams and Jeffrey Hutzelman.


7.  References

7.1.  Normative References

   [GSS-API]  Linn, J., "Generic Security Service Application Program
              Interface Version 2, Update 1", RFC 2743, January 2000.

   [KEYWORDS]
              Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [KRB5GSS]  Linn, J., "The Kerberos Version 5 GSS-API Mechanism",
              RFC 1964, June 1996.

   [RFC4121]  Zhu, L., Jaganathan, K., and S. Hartman, "The Kerberos
              Version 5 Generic Security Service Application Program
              Interface (GSS-API) Mechanism: Version 2", RFC 4121,
              July 2005.

   [SASL]     Myers, J., "Simple Authentication and Security Layer
              (SASL)", RFC 2222, October 1997.

   [SASL[2]]  Melnikov, A., "Simple Authentication and Security Layer
              (SASL)", draft-ietf-sasl-rfc2222bis (work in progress),
              June 2004.

   [UTF8]     Yergeau, F., "UTF-8, a transformation format of ISO
              10646", RFC 3629, November 2003.

7.2.  Informative References

















Melnikov                Expires December 1, 2006                [Page 8]
\f
Internet-Draft  The Kerberos V5 ("GSSAPI") SASL mechanism       May 2006


Author's Address

   Alexey Melnikov (Ed.)
   Isode Limited
   5 Castle Business Village
   36 Station Road
   Hampton, Middlesex  TW12 2BX
   UK

   Email: Alexey.Melnikov@isode.com
   URI:   http://www.melnikov.ca/








































Melnikov                Expires December 1, 2006                [Page 9]
\f
Internet-Draft  The Kerberos V5 ("GSSAPI") SASL mechanism       May 2006


Intellectual Property Statement

   The IETF takes no position regarding the validity or scope of any
   Intellectual Property Rights or other rights that might be claimed to
   pertain to the implementation or use of the technology described in
   this document or the extent to which any license under such rights
   might or might not be available; nor does it represent that it has
   made any independent effort to identify any such rights.  Information
   on the procedures with respect to rights in RFC documents can be
   found in BCP 78 and BCP 79.

   Copies of IPR disclosures made to the IETF Secretariat and any
   assurances of licenses to be made available, or the result of an
   attempt made to obtain a general license or permission for the use of
   such proprietary rights by implementers or users of this
   specification can be obtained from the IETF on-line IPR repository at
   http://www.ietf.org/ipr.

   The IETF invites any interested party to bring to its attention any
   copyrights, patents or patent applications, or other proprietary
   rights that may cover technology that may be required to implement
   this standard.  Please address the information to the IETF at
   ietf-ipr@ietf.org.


Disclaimer of Validity

   This document and the information contained herein are provided on an
   "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
   OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
   ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
   INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
   INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
   WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.


Copyright Statement

   Copyright (C) The Internet Society (2006).  This document is subject
   to the rights, licenses and restrictions contained in BCP 78, and
   except as set forth therein, the authors retain all their rights.


Acknowledgment

   Funding for the RFC Editor function is currently provided by the
   Internet Society.




Melnikov                Expires December 1, 2006               [Page 10]
\f