Using Generic Security Service Application Program Interface (GSS-API) Mechanisms in Simple Authentication and Security Layer (SASL): The GS2 Mechanism Family
draft-josefsson-kitten-gs2bis-00

Abstract

This document describes how to use a Generic Security Service Application Program Interface (GSS-API) mechanism in the Simple Authentication and Security Layer (SASL) framework. This is done by defining a new SASL mechanism family, called GS2. This mechanism family offers a number of improvements over the previous "SASL/GSSAPI" mechanism: it is more general, uses fewer messages for the authentication phase in some cases, and supports negotiable use of channel binding. This is an update of RFC 5801 that relaxes the requirement for channel binding support and mutual authentication in the underlying GSS-API mechanism.

Status of this Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.

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.”

This Internet-Draft will expire on September 4, 2014.

Copyright Notice

Copyright (c) 2014 IETF Trust and the persons identified as the document authors. All rights reserved.

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.

This document may contain material from IETF Documents or IETF Contributions published or made publicly available before November 10, 2008. The person(s) controlling the copyright in some of this material may not have granted the IETF Trust the right to allow modifications of such material outside the IETF Standards Process. Without obtaining an adequate license from the person(s) controlling the copyright in such materials, this document may not be modified outside the IETF Standards Process, and derivative works of it may not be created outside the IETF Standards Process, except to format it for publication as an RFC or to translate it into languages other than English.

Table of Contents

1.  Introduction
2.  Conventions Used in This Document
3.  Mechanism Name
    3.1.  Generating SASL Mechanism Names from GSS-API OIDs
    3.2.  Computing Mechanism Names Manually
    3.3.  Examples
    3.4.  Grandfathered Mechanism Names
4.  SASL Authentication Exchange Message Format
5.  Channel Bindings
    5.1.  Content of GSS-CHANNEL-BINDINGS Structure
    5.2.  Default Channel Binding
6.  When the mechanism does not support channel binding and/or mutual authentication
7.  Examples
8.  Authentication Conditions
9.  GSS-API Parameters
10.  Naming
11.  GSS_Inquire_SASLname_for_mech Call
    11.1.  gss_inquire_saslname_for_mech
12.  GSS_Inquire_mech_for_SASLname Call
    12.1.  gss_inquire_mech_for_saslname
13.  Security Layers
14.  Interoperability with the SASL GSSAPI Mechanism
    14.1.  The Interoperability Problem
    14.2.  Resolving the Problem
    14.3.  Additional Recommendations
15.  GSS-API Mechanisms That Negotiate Other Mechanisms
    15.1.  The Interoperability Problem
    15.2.  Security Problem
    15.3.  Resolving the Problems
16.  IANA Considerations
17.  Security Considerations
18.  Acknowledgements
19.  References
    19.1.  Normative References
    19.2.  Informative References
§  Author's Address

1.  Introduction

Generic Security Service Application Program Interface (GSS-API) [RFC2743] (Linn, J., “Generic Security Service Application Program Interface Version 2, Update 1,” January 2000.) is a framework that provides security services to applications using a variety of authentication mechanisms. Simple Authentication and Security Layer (SASL) [RFC4422] (Melnikov, A. and K. Zeilenga, “Simple Authentication and Security Layer (SASL),” June 2006.) is a framework to provide authentication and security layers for connection-based protocols, also using a variety of mechanisms. This document describes how to use a GSS-API mechanism as though it were a SASL mechanism. This facility is called GS2 -- a moniker that indicates that this is the second GSS-API->SASL mechanism bridge. The original GSS-API->SASL mechanism bridge was specified by [RFC2222] (Myers, J., “Simple Authentication and Security Layer (SASL),” October 1997.), now [RFC4752] (Melnikov, A., “The Kerberos V5 ("GSSAPI") Simple Authentication and Security Layer (SASL) Mechanism,” November 2006.); we shall sometimes refer to the original bridge as GS1 in this document.

All GSS-API mechanisms are implicitly registered for use within SASL by this specification. The SASL mechanisms defined in this document are known as the GS2 family of mechanisms.

The GS1 bridge failed to gain wide deployment for any GSS-API mechanism other than "The Kerberos Version 5 GSS-API Mechanism" [RFC1964] (Linn, J., “The Kerberos Version 5 GSS-API Mechanism,” 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,” July 2005.), and has a number of problems that led us to desire a new bridge. Specifically, a) GS1 was not round-trip optimized and b) GS1 did not support channel binding [RFC5056] (Williams, N., “On the Use of Channel Bindings to Secure Channels,” November 2007.). These problems and the opportunity to create the next SASL password-based mechanism, "Salted Challenge Response Authentication Mechanism (SCRAM) SASL and GSS-API Mechanisms" (Newman, C., Menon-Sen, A., Melnikov, A., and N. Williams, “Salted Challenge Response Authentication Mechanism (SCRAM) SASL and GSS-API Mechanisms,” July 2010.) [RFC5802], as a GSS-API mechanism used by SASL applications via GS2, provide the motivation for GS2.

In particular, the current consensus of the SASL community appears to be that SASL "security layers" (i.e., confidentiality and integrity protection of application data after authentication) are too complex and redundant because SASL applications tend to have an option to run over a Transport Layer Security (TLS) [RFC5246] (Dierks, T. and E. Rescorla, “The Transport Layer Security (TLS) Protocol Version 1.2,” August 2008.) channel. Use of SASL security layers is best replaced with channel binding to a TLS channel.

GS2 is designed to be as simple as possible. It adds to GSS-API security context token exchanges only the bare minimum to support SASL semantics and negotiation of use of channel binding. Specifically, GS2 adds a small header (a few bytes plus the length of the client-requested SASL authorization identity) to the initial GSS-API context token and to the application channel binding data. GS2 uses SASL mechanism negotiation to implement channel binding negotiation. Security-relevant GS2 plaintext is protected via the use of GSS-API channel binding. Additionally, to simplify the implementation of GS2 mechanisms for implementors who will not implement a GSS-API framework, we compress the initial security context token header required by [RFC2743] (Linn, J., “Generic Security Service Application Program Interface Version 2, Update 1,” January 2000.), Section 3.1.

GS2 does not protect any plaintext exchanged outside GS2, such as SASL mechanism negotiation plaintext, or application messages following authentication. But using channel binding to a secure channel over which all SASL and application plaintext is sent will cause all that plaintext to be authenticated.

2.  Conventions Used in This Document

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119] (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.).

The document uses many terms and function names defined in [RFC2743] (Linn, J., “Generic Security Service Application Program Interface Version 2, Update 1,” January 2000.), as updated by [RFC5554] (Williams, N., “Clarifications and Extensions to the Generic Security Service Application Program Interface (GSS-API) for the Use of Channel Bindings,” May 2009.).

3.  Mechanism Name

There are two SASL mechanism names for any GSS-API mechanism used through this facility. One denotes that the server supports channel binding. The other denotes that it does not.

The SASL mechanism name for a GSS-API mechanism is that which is provided by that mechanism when it was specified, if one was specified. This name denotes that the server does not support channel binding. Add the suffix "-PLUS" and the resulting name denotes that the server does support channel binding. SASL implementations can use the GSS_Inquire_SASLname_for_mech call (see below) to query for the SASL mechanism name of a GSS-API mechanism.

If the GSS_Inquire_SASLname_for_mech interface is not used, the GS2 implementation needs some other mechanism to map mechanism Object Identifiers (OIDs) to SASL names internally. In this case, the implementation can only support the mechanisms for which it knows the SASL name. If GSS_Inquire_SASLname_for_mech() fails and the GS2 implementation cannot map the OID to a SASL mechanism name via some other means, then the GS2 implementation MUST NOT use the given GSS-API mechanism.

3.1.  Generating SASL Mechanism Names from GSS-API OIDs

For GSS-API mechanisms whose SASL names are not defined together with the GSS-API mechanism or in this document, the SASL mechanism name is concatenation of the string "GS2-" and the Base32 encoding (Josefsson, S., “The Base16, Base32, and Base64 Data Encodings,” October 2006.) [RFC4648] (with an uppercase alphabet) of the first 55 bits of the binary SHA-1 hash (National Institute of Standards and Technology, “Secure Hash Standard,” April 1995.) [FIPS.180‑1.1995] string computed over the ASN.1 DER encoding (International Telephone and Telegraph Consultative Committee, “ASN.1 encoding rules: Specification of basic encoding Rules (BER), Canonical encoding rules (CER) and Distinguished encoding rules (DER),” July 2002.) [CCITT.X690.2002], including the tag and length octets, of the GSS-API mechanism's Object Identifier. The Base32 rules on padding characters and characters outside of the Base32 alphabet are not relevant to this use of Base32. If any padding or non-alphabet characters are encountered, the name is not a GS2 family mechanism name. This name denotes that the server does not support channel binding. Add the suffix "-PLUS" and the resulting name denotes that the server does support channel binding.

A GS2 mechanism that has a non-OID-derived SASL mechanism name is said to have a "user-friendly SASL mechanism name".

3.2.  Computing Mechanism Names Manually

The hash-derived GS2 SASL mechanism name may be computed manually. This is useful when the set of supported GSS-API mechanisms is known in advance. This eliminates the need to implement Base32, SHA-1, and DER in the SASL mechanism. The computed mechanism name can be used directly in the implementation, and the implementation need not be concerned if the mechanism is part of a mechanism family.

3.3.  Examples

The OID for the Simple Public-Key GSS-API Mechanism (SPKM-1) (Adams, C., “The Simple Public-Key GSS-API Mechanism (SPKM),” October 1996.) [RFC2025] is 1.3.6.1.5.5.1.1. The ASN.1 DER encoding of the OID, including the tag and length, is (in hex) 06 07 2b 06 01 05 05 01 01. The SHA-1 hash of the ASN.1 DER encoding is (in hex) 1c f8 f4 2b 5a 9f 80 fa e9 f8 31 22 6d 5d 9d 56 27 86 61 ad. Convert the first 7 octets to binary, drop the last bit, and re-group them in groups of 5, and convert them back to decimal, which results in these computations:

hex:
1c f8 f4 2b 5a 9f 80

binary:
00011100 11111000 11110100 00101011 01011010
10011111 1000000

binary in groups of 5:
00011 10011 11100 01111 01000 01010 11010 11010
10011 11110 00000

decimal of each group:
3 19 28 15 8 10 26 26 19 30 0

base32 encoding:
D T 4 P I K 2 2 T 6 A

The last step translates each decimal value using table 3 in Base32 (Josefsson, S., “The Base16, Base32, and Base64 Data Encodings,” October 2006.) [RFC4648]. Thus, the SASL mechanism name for the SPKM-1 GSSAPI mechanism is "GS2-DT4PIK22T6A".

The OID for the Kerberos V5 GSS-API mechanism (Linn, J., “The Kerberos Version 5 GSS-API Mechanism,” June 1996.) [RFC1964] is 1.2.840.113554.1.2.2 and its DER encoding is (in hex) 06 09 2A 86 48 86 F7 12 01 02 02. The SHA-1 hash is 82 d2 73 25 76 6b d6 c8 45 aa 93 25 51 6a fc ff 04 b0 43 60. Convert the 7 octets to binary, drop the last bit, and re-group them in groups of 5, and convert them back to decimal, which results in these computations:

hex:
82 d2 73 25 76 6b d6

binary:
10000010 11010010 01110011 00100101 01110110
01101011 1101011

binary in groups of 5:
10000 01011 01001 00111 00110 01001 01011 10110
01101 01111 01011

decimal of each group:
16 11 9 7 6 9 11 22 13 15 11

base32 encoding:
Q L J H G J L W N P L

The last step translates each decimal value using table 3 in Base32 (Josefsson, S., “The Base16, Base32, and Base64 Data Encodings,” October 2006.) [RFC4648]. Thus, the SASL mechanism name for the Kerberos V5 GSS-API mechanism would be "GS2-QLJHGJLWNPL" and (because this mechanism supports channel binding) "GS2-QLJHGJLWNPL-PLUS". Instead, the next section assigns the Kerberos V5 mechanism a non-hash-derived mechanism name.

3.4.  Grandfathered Mechanism Names

Some older GSS-API mechanisms were not specified with a SASL GS2 mechanism name. Using a shorter name can be useful, nonetheless. We specify the names "GS2-KRB5" and "GS2-KRB5-PLUS" for the Kerberos V5 mechanism, to be used as if the original specification documented it, see Section 16 (IANA Considerations).

4.  SASL Authentication Exchange Message Format

During the SASL authentication exchange for GS2, a number of messages following the following format are sent between the client and server. On success, this number is the same as the number of context tokens that the GSS-API mechanism would normally require in order to establish a security context. On failures, the exchange can be terminated early by any party.

When using a GS2 mechanism the SASL client is always a GSS-API initiator and the SASL server is always a GSS-API acceptor. The client calls GSS_Init_sec_context and the server calls GSS_Accept_sec_context.

All the SASL authentication messages exchanged are exactly the same as the security context tokens of the GSS-API mechanism, except for the initial security context token.

The client and server MAY send GSS-API error tokens (tokens output by GSS_Init_sec_context() or GSS_Accept_sec_context() when the major status code is other than GSS_S_COMPLETE or GSS_S_CONTINUE_NEEDED). As this indicates an error condition, after sending the token, the sending side should fail the authentication.

The initial security context token is modified as follows:

• The initial context token header (see Section 3.1 of [RFC2743] (Linn, J., “Generic Security Service Application Program Interface Version 2, Update 1,” January 2000.)) MUST be removed if present. If the header is not present, the client MUST send a "gs2-nonstd-flag" flag (see below). On the server side, this header MUST be recomputed and restored prior to passing the token to GSS_Accept_sec_context, except when the "gs2-nonstd-flag" is sent.
• A GS2 header MUST be prefixed to the resulting initial context token. This header has the form "gs2-header" given below in ABNF [RFC5234] (Crocker, D. and P. Overell, “Augmented BNF for Syntax Specifications: ABNF,” January 2008.).

The figure below describes the permissible attributes, their use, and the format of their values. All attribute names are single US-ASCII letters and are case sensitive.

 UTF8-1-safe    = %x01-2B / %x2D-3C / %x3E-7F
                  ;; As UTF8-1 in RFC 3629 except
                  ;; NUL, "=", and ",".
 UTF8-2         = <as defined in RFC 3629 (STD 63)>
 UTF8-3         = <as defined in RFC 3629 (STD 63)>
 UTF8-4         = <as defined in RFC 3629 (STD 63)>
 UTF8-char-safe = UTF8-1-safe / UTF8-2 / UTF8-3 / UTF8-4

 saslname       = 1*(UTF8-char-safe / "=2C" / "=3D")
 gs2-authzid    = "a=" saslname
                   ;; GS2 has to transport an authzid since
                   ;; the GSS-API has no equivalent
 gs2-nonstd-flag = "F"
                   ;; "F" means the mechanism is not a
                   ;; standard GSS-API mechanism in that the
                   ;; RFC 2743, Section 3.1 header was missing
 cb-name         = 1*(ALPHA / DIGIT / "." / "-")
                   ;; See RFC 5056, Section 7.
 gs2-cb-flag     = ("p=" cb-name) / "n" / "y"
                   ;; GS2 channel binding (CB) flag
                   ;; "p" -> client supports and used CB
                   ;; "n" -> client does not support CB
                   ;; "y" -> client supports CB, thinks the server
                   ;;           does not
 gs2-header = [gs2-nonstd-flag ","] gs2-cb-flag "," [gs2-authzid] ","
                     ;; The GS2 header is gs2-header.

When the "gs2-nonstd-flag" flag is present, the client did not find/remove a token header ([RFC2743] (Linn, J., “Generic Security Service Application Program Interface Version 2, Update 1,” January 2000.), Section 3.1) from the initial token returned by GSS_Init_sec_context. This signals to the server that it MUST NOT re-add the data that is normally removed by the client.

The "gs2-cb-flag" signals the channel binding mode. One of "p", "n", or "y" is used. A "p" means the client supports and used a channel binding, and the name of the channel binding type is indicated. An "n" means that the client does not support channel binding. A "y" means the client supports channel binding, but believes the server does not support it, so it did not use a channel binding. See the next section for more details.

The "gs2-authzid" holds the SASL authorization identity. It is encoded using UTF-8 (Yergeau, F., “UTF-8, a transformation format of ISO 10646,” November 2003.) [RFC3629] with three exceptions:

• The NUL character is forbidden as required by section 3.4.1 of [RFC4422] (Melnikov, A. and K. Zeilenga, “Simple Authentication and Security Layer (SASL),” June 2006.).
• The server MUST replace any "," (comma) in the string with "=2C".
• The server MUST replace any "=" (equals) in the string with "=3D".

Upon receipt of this value, the server verifies its correctness according to the used SASL protocol profile. Failed verification results in a failed authentication exchange.

5.  Channel Bindings

GS2 supports channel binding to external secure channels, such as TLS. Clients and servers may or may not support channel binding; therefore, the use of channel binding is negotiable. However, GS2 does not provide security layers; therefore, it is imperative that GS2 provide integrity protection for the negotiation of channel binding.

Use of channel binding is negotiated as follows:

• Servers that support the use of channel binding SHOULD advertise both the non-PLUS and PLUS-variant of each GS2 mechanism name. If the server cannot support channel binding, it SHOULD advertise only the non-PLUS-variant. If the server would never succeed in the authentication of the non-PLUS-variant due to policy reasons, it MUST advertise only the PLUS-variant.
• If the client supports channel binding and the server does not appear to (i.e., the client did not see the -PLUS name advertised by the server), then the client MUST NOT use an "n" gs2-cb-flag.
• Clients that support mechanism negotiation and channel binding MUST use a "p" gs2-cb-flag when the server offers the PLUS-variant of the desired GS2 mechanism.
• If the client does not support channel binding, then it MUST use an "n" gs2-cb-flag. Conversely, if the client requires the use of channel binding then it MUST use a "p" gs2-cb-flag. Clients that do not support mechanism negotiation never use a "y" gs2-cb-flag, they use either "p" or "n" according to whether they require and support the use of channel binding or whether they do not, respectively.
• The client generates the chan_bindings input parameter for GSS_Init_sec_context as described below.
• Upon receipt of the initial authentication message, the server checks the gs2-cb-flag in the GS2 header and constructs a chan_bindings parameter for GSS_Accept_sec_context as described below. If the client channel binding flag was "y" and the server did advertise support for channel bindings (by advertising the PLUS-variant of the mechanism chosen by the client), then the server MUST fail authentication. If the client channel binding flag was "p" and the server does not support the indicated channel binding type, then the server MUST fail authentication.
• If the client used an "n" gs2-cb-flag and the server requires the use of channel binding, then the server MUST fail authentication.

  FLAG CLIENT CB SUPPORT   SERVER CB SUPPORT DISPOSITION
  ---- -----------------   ----------------- -----------

  n    no support          N/A               If server disallows
                                             non-channel-bound
                                             authentication, then
                                             fail

  y    Yes, not required   No                Authentication may
                                             succeed; CB not used

  y    Yes, not required   Yes               Authentication must fail

  p    Yes                 Yes               Authentication may
                                             succeed, with CB used

  p    Yes                 No                Authentication will fail

  N/A  Yes, required       No                Client does not even try

For more discussion of channel bindings, and the syntax of the channel binding data for various security protocols, see [RFC5056] (Williams, N., “On the Use of Channel Bindings to Secure Channels,” November 2007.).

5.1.  Content of GSS-CHANNEL-BINDINGS Structure

The calls to GSS_Init_sec_context and GSS_Accept_sec_context take a chan_bindings parameter. The value is a GSS-CHANNEL-BINDINGS structure [RFC5554] (Williams, N., “Clarifications and Extensions to the Generic Security Service Application Program Interface (GSS-API) for the Use of Channel Bindings,” May 2009.).

The initiator-address-type and acceptor-address-type fields of the GSS-CHANNEL-BINDINGS structure MUST be set to 0. The initiator-address and acceptor-address fields MUST be the empty string.

The application-data field MUST be set to the gs2-header, excluding the initial [gs2-nonstd-flag ","] part, concatenated with, when a gs2-cb-flag of "p" is used, the application's channel binding data.

5.2.  Default Channel Binding

A default channel binding type agreement process for all SASL application protocols that do not provide their own channel binding type agreement is provided as follows.

'tls-unique' is the default channel binding type for any application that doesn't specify one.

Servers MUST implement the "tls-unique" [RFC5929] (Altman, J., Williams, N., and L. Zhu, “Channel Bindings for TLS,” July 2010.) channel binding type, if they implement any channel binding. Clients SHOULD implement the "tls-unique" channel binding type, if they implement any channel binding. Clients and servers SHOULD choose the highest-layer/innermost end-to-end TLS channel as the channel to which to bind.

Servers MUST choose the channel binding type indicated by the client, or fail authentication if they don't support it.

6.  When the mechanism does not support channel binding and/or mutual authentication

Some authentication mechanisms does not offer mutual authentication or is unable to provide channel bindings. This is unfortunate, and usually suggests that the authentication mechanism offers limited authentication functionality. However there are situations when the lack of this functionality can be mitigated with other protection mechanisms, leading to acceptable overall security. Being able to define and use an authentication mechanism as a GSS-API mechanism and then use that GSS-API mechanism in the SASL environment using GS2 has advantages; for example, being able to re-use existing generic GS2 implementations. Further, being able to express all mechanisms that can be expressed as a GSS-API mechanisms as a SASL mechanism (and vice versa) provides design elegance and framework replacability. Therefor, this document relaxes the requirement that the GSS-API mechanism support channel bindings and/or mutual authentication. Implementing and deploying applications that supports those mechanism require some consideration, and this section discuss the relevant areas.

For the discussion it helps to understand what happens with the GS2 bridge when a GSS-API mechanism does not offer channel bindings or mutual authentication. When channel bindings is not supported by the underlying mechanism, GS2 cannot protect its data (essentially: the channel binding flag and the SASL authorization identity). This means that the security of the channel binding mode breaks down and that the other side cannot trust the SASL authorization identity. When mutual authentication is not happening, the client cannot know that it sends its data to the intended server.

It is acceptable to use these mechanisms with GS2 in some situations. For example, if the client uses TLS against a server, and the client verify the server's certificate properly so that server authentication has occured, then authenticating the client to the server using a "weak" GSS-API mechanism will technically work. The security properties will not be as good as they would have been if the underlying mechanism supported channel binding or mutual authentication, however they become as good as possible.

This document relaxes the requirements on GSS-API mechanism so that all GSS-API mechanism can be expressed in GS2. For these mechanisms, the "gs2-cb-flag" value MUST always be "n", and the PLUS-variant of the GS2 mechanism name MUST NOT be advertised or negotiated.

The SAML SASL bridge (Wierenga, K., Lear, E., and S. Josefsson, “A Simple Authentication and Security Layer (SASL) and GSS-API Mechanism for the Security Assertion Markup Language (SAML),” April 2012.) [RFC6595] and the SAML OpenID bridge (Lear, E., Tschofenig, H., Mauldin, H., and S. Josefsson, “A Simple Authentication and Security Layer (SASL) and Generic Security Service Application Program Interface (GSS-API) Mechanism for OpenID,” May 2012.) [RFC6616] are two examples of documents that describe such bridges. These documents did not meet the requirements of the original GS2 bridge, but with the update in this document they are conformant. Note that both documents had discussions describing this aspect and sufficient requirements for safe implementation and deployment.

7.  Examples

Example #1: a one round-trip GSS-API context token exchange, no channel binding, optional authzid given.

      C: Request authentication exchange
      S: Empty Challenge
      C: n,a=someuser,<initial context token with standard
                         header removed>
      S: Send reply context token as is
      C: Empty message
      S: Outcome of authentication exchange

Example #2: a one and one half round-trip GSS-API context token exchange, no channel binding.

      C: Request authentication exchange
      S: Empty Challenge
      C: n,,<initial context token with standard
                         header removed>
      S: Send reply context token as is
      C: Send reply context token as is
      S: Outcome of authentication exchange

Example #3: a two round-trip GSS-API context token exchange, no channel binding, no standard token header.

      C: Request authentication exchange
      S: Empty Challenge
      C: F,n,,<initial context token without
                          standard header>
      S: Send reply context token as is
      C: Send reply context token as is
      S: Send reply context token as is
      C: Empty message
      S: Outcome of authentication exchange

Example #4: using channel binding, optional authzid given.

      C: Request authentication exchange
      S: Empty Challenge
      C: p=tls-unique,a=someuser,<initial context token with standard
                             header removed>
      S: Send reply context token as is
      ...

Example #5: using channel binding.

      C: Request authentication exchange
      S: Empty Challenge
      C: p=tls-unique,,<initial context token with standard
                             header removed>
      S: Send reply context token as is
      ...

Example #6: using non-standard channel binding (requires out-of-band negotiation).

      C: Request authentication exchange
      S: Empty Challenge
      C: p=tls-server-end-point,,<initial context token with standard
                             header removed>
      S: Send reply context token as is
      ...

Example #7: client supports channel bindings but server does not, optional authzid given.

      C: Request authentication exchange
      S: Empty Challenge
      C: y,a=someuser,<initial
                        context token with standard header removed>
      S: Send reply context token as is
      ...

GSS-API authentication is always initiated by the client. The SASL framework allows either the client or the server to initiate authentication. In GS2, the server will send an initial empty challenge (zero-byte string) if it has not yet received a token from the client. See Section 3 of [RFC4422] (Melnikov, A. and K. Zeilenga, “Simple Authentication and Security Layer (SASL),” June 2006.).

8.  Authentication Conditions

Authentication MUST NOT succeed if any one of the following conditions are true:

• If GSS_Init/Accept_sec_context returns anything other than GSS_S_CONTINUE_NEEDED or GSS_S_COMPLETE.
• If the client's initial GS2 header does not match the ABNF.
• In particular, if the initial character of the client message is anything except "F", "p", "n", or "y".
• If the client's GS2 channel binding flag was "y" and the server supports channel bindings.
• If the client's GS2 channel binding flag was "p" and the server does not support the indicated channel binding.
• If the client requires use of channel binding and the server did not advertise support for channel binding.
• If authorization of client principal (i.e., src_name in GSS_Accept_sec_context) to requested authzid failed.
• If the client is not authorized to the requested authzid or an authzid could not be derived from the client's initiator principal name.

9.  GSS-API Parameters

GS2 does not use any GSS-API per-message tokens. Therefore, the per-message token ret_flags from GSS_Init_sec_context() and GSS_Accept_sec_context() are irrelevant; implementations SHOULD NOT set the per-message req_flags.

The mutual_req_flag MUST be set. Clients MUST check that the corresponding ret_flag is set when the context is fully established, else authentication MUST fail.

Use or non-use of deleg_req_flag and anon_req_flag is an implementation-specific detail. SASL and GS2 implementors are encouraged to provide programming interfaces by which clients may choose to delegate credentials and by which servers may receive them. SASL and GS2 implementors are encouraged to provide programming interfaces that provide a good mapping of GSS-API naming options.

10.  Naming

There is no requirement that any particular GSS-API name-types be used. However, typically, SASL servers will have host-based acceptor principal names (see [RFC2743] (Linn, J., “Generic Security Service Application Program Interface Version 2, Update 1,” January 2000.), Section 4.1) and clients will typically have username initiator principal names (see [RFC2743] (Linn, J., “Generic Security Service Application Program Interface Version 2, Update 1,” January 2000.), Section 4.2). When a host-based acceptor principal name is used ("service@hostname"), "service" is the service name specified in the protocol's profile and "hostname" is the fully qualified host name of the server.

11.  GSS_Inquire_SASLname_for_mech Call

We specify a new GSS-API utility function to allow SASL implementations to more efficiently identify the GSS-API mechanism to which a particular SASL mechanism name refers.

   Inputs:

   o  desired_mech OBJECT IDENTIFIER

   Outputs:

   o  major_status INTEGER

   o  minor_status INTEGER

   o  sasl_mech_name UTF-8 STRING -- SASL name for this
      mechanism; caller must release with
      GSS_Release_buffer()

   o  mech_name UTF-8 STRING -- name of this mechanism, possibly
      localized; caller must release with GSS_Release_buffer()

   o  mech_description UTF-8 STRING -- possibly localized
      description of this mechanism; caller must release with
      GSS_Release_buffer()

   Return major_status codes:

   o  GSS_S_COMPLETE indicates successful completion, and that
      output parameters holds correct information.

   o  GSS_S_BAD_MECH indicates that a desired_mech was unsupported
      by the GSS-API implementation.

   o  GSS_S_FAILURE indicates that the operation failed for reasons
      unspecified at the GSS-API level.

   The GSS_Inquire_SASLname_for_mech call is used to get the SASL
   mechanism name for a GSS-API mechanism.  It also returns a name
   and description of the mechanism in user-friendly form.

   The output variable sasl_mech_name will hold the IANA registered
   mechanism name for the GSS-API mechanism, or if none is
   registered, a mechanism name computed from the OID as described
   in Section 3.1 of this document.

11.1.  gss_inquire_saslname_for_mech

The C binding for the GSS_Inquire_SASLname_for_mech call is as follows.

As mentioned in [RFC2744] (Wray, J., “Generic Security Service API Version 2 : C-bindings,” January 2000.), routines may return GSS_S_FAILURE, indicating an implementation-specific or mechanism-specific error condition, further details of which are reported via the minor_status parameter.

   OM_uint32 gss_inquire_saslname_for_mech(
     OM_uint32     *minor_status,
     const gss_OID  desired_mech,
     gss_buffer_t   sasl_mech_name,
     gss_buffer_t   mech_name,
     gss_buffer_t   mech_description
   );

   Purpose:

   Output the SASL mechanism name of a GSS-API mechanism.
   It also returns a name and description of the mechanism in a
   user-friendly form.

   Parameters:

   minor_status      Integer, modify
                     Mechanism-specific status code.

   desired_mech      OID, read
                     Identifies the GSS-API mechanism to query.

   sasl_mech_name    buffer, character-string, modify, optional
                     Buffer to receive SASL mechanism name.
                     The application must free storage associated
                     with this name after use with a call to
                     gss_release_buffer().

   mech_name         buffer, character-string, modify, optional
                     Buffer to receive human-readable mechanism name.
                     The application must free storage associated
                     with this name after use with a call to
                     gss_release_buffer().

   mech_description  buffer, character-string, modify, optional
                     Buffer to receive description of mechanism.
                     The application must free storage associated
                     with this name after use with a call to
                     gss_release_buffer().

   Function value:   GSS status code:

   GSS_S_COMPLETE    Successful completion.

   GSS_S_BAD_MECH    The desired_mech OID is unsupported.

12.  GSS_Inquire_mech_for_SASLname Call

To allow SASL clients to more efficiently identify to which GSS-API mechanism a particular SASL mechanism name refers, we specify a new GSS-API utility function for this purpose.

   Inputs:

   o  sasl_mech_name UTF-8 STRING -- SASL name of mechanism.

   Outputs:

   o  major_status INTEGER

   o  minor_status INTEGER

   o  mech_type OBJECT IDENTIFIER -- must be explicit mechanism,
      and not "default" specifier.  Caller should treat as read-only
      and should not attempt to release.

   Return major_status codes:

   o  GSS_S_COMPLETE indicates successful completion, and that output
      parameters holds correct information.

   o  GSS_S_BAD_MECH indicates that no supported GSS-API mechanism
      had the indicated sasl_mech_name.

   o  GSS_S_FAILURE indicates that the operation failed for reasons
      unspecified at the GSS-API level.

   The GSS_Inquire_mech_for_SASLname call is used to get the GSS-API
   mechanism OID associated with a SASL mechanism name.

12.1.  gss_inquire_mech_for_saslname

The C binding for the GSS_Inquire_mech_for_SASLname call is as follows.

As mentioned in [RFC2744] (Wray, J., “Generic Security Service API Version 2 : C-bindings,” January 2000.), routines may return GSS_S_FAILURE, indicating an implementation-specific or mechanism-specific error condition, further details of which are reported via the minor_status parameter.

   OM_uint32 gss_inquire_mech_for_saslname(
     OM_uint32           *minor_status,
     const gss_buffer_t   sasl_mech_name,
     gss_OID             *mech_type
   );

   Purpose:

   Output GSS-API mechanism OID of mechanism associated with given
   sasl_mech_name.

   Parameters:

   minor_status      Integer, modify
                     Mechanism-specific status code.

   sasl_mech_name    buffer, character-string, read
                     Buffer with SASL mechanism name.

   mech_type         OID, modify, optional
                     Actual mechanism used.  The OID returned via
                     this parameter will be a pointer to static
                     storage that should be treated as read-only.
                     In particular, the application should not attempt
                     to free it.  Specify NULL if not required.

   Function value:   GSS status code:

   GSS_S_COMPLETE    Successful completion.

   GSS_S_BAD_MECH    There is no GSS-API mechanism known
                     as sasl_mech_name.

13.  Security Layers

GS2 does not support SASL security layers. Applications that need integrity or confidentiality protection can use either channel binding to a secure external channel or another SASL mechanism that does provide security layers.

14.  Interoperability with the SASL GSSAPI Mechanism

The Kerberos V5 GSS-API (Linn, J., “The Kerberos Version 5 GSS-API Mechanism,” June 1996.) [RFC1964] mechanism is currently used in SASL under the name GSSAPI, see [RFC4752] (Melnikov, A., “The Kerberos V5 ("GSSAPI") Simple Authentication and Security Layer (SASL) Mechanism,” November 2006.). The Kerberos V5 mechanism may also be used with the GS2 family. This causes an interoperability problem, which is discussed and resolved below.

14.1.  The Interoperability Problem

The SASL "GSSAPI" mechanism is not wire compatible with the Kerberos V GSS-API mechanism used as a SASL GS2 mechanism.

If a client (or server) only support Kerberos V5 under the "GSSAPI" name, and the server (or client) only support Kerberos V5 under the GS2 family, the mechanism negotiation will fail.

14.2.  Resolving the Problem

If the Kerberos V5 mechanism is supported under GS2 in a server, the server SHOULD also support Kerberos V5 through the "GSSAPI" mechanism, to avoid interoperability problems with older clients.

Reasons for violating this recommendation may include security considerations regarding the absent features in the GS2 mechanism. The SASL "GSSAPI" mechanism lacks support for channel bindings, which means that using an external secure channel may not be sufficient protection against active attackers (see [RFC5056] (Williams, N., “On the Use of Channel Bindings to Secure Channels,” November 2007.) and [MITM] (Asokan, N., Niemi, V., and K. Nyberg, “Man-in-the-Middle in Tunnelled Authentication,” .)).

14.3.  Additional Recommendations

If the application requires SASL security layers, then it MUST use the SASL "GSSAPI" mechanism [RFC4752] (Melnikov, A., “The Kerberos V5 ("GSSAPI") Simple Authentication and Security Layer (SASL) Mechanism,” November 2006.) instead of "GS2-KRB5" or "GS2-KRB5-PLUS".

If the application can use channel binding to an external channel, then it is RECOMMENDED that it select Kerberos V5 through the GS2 mechanism rather than the "GSSAPI" mechanism.

15.  GSS-API Mechanisms That Negotiate Other Mechanisms

A GSS-API mechanism that negotiates other mechanisms will interact badly with the SASL mechanism negotiation. There are two problems. The first is an interoperability problem and the second is a security concern. The problems are described and resolved below.

15.1.  The Interoperability Problem

If a client implements GSS-API mechanism X, potentially negotiated through a GSS-API mechanism Y, and the server also implements GSS-API mechanism X negotiated through a GSS-API mechanism Z, the authentication negotiation will fail.

15.2.  Security Problem

If a client's policy is to first prefer GSSAPI mechanism X, then non-GSSAPI mechanism Y, then GSSAPI mechanism Z, and if a server supports mechanisms Y and Z but not X, then if the client attempts to negotiate mechanism X by using a GSS-API mechanism that negotiates other mechanisms (such as Simple and Protected GSS-API Negotiation (SPNEGO) [RFC4178] (Zhu, L., Leach, P., Jaganathan, K., and W. Ingersoll, “The Simple and Protected Generic Security Service Application Program Interface (GSS-API) Negotiation Mechanism,” October 2005.)), it may end up using mechanism Z when it ideally should have used mechanism Y. For this reason, the use of GSS-API mechanisms that negotiate other mechanisms is disallowed under GS2.

15.3.  Resolving the Problems

GSS-API mechanisms that negotiate other mechanisms MUST NOT be used with the GS2 SASL mechanism. Specifically, SPNEGO [RFC4178] (Zhu, L., Leach, P., Jaganathan, K., and W. Ingersoll, “The Simple and Protected Generic Security Service Application Program Interface (GSS-API) Negotiation Mechanism,” October 2005.) MUST NOT be used as a GS2 mechanism. To make this easier for SASL implementations, we assign a symbolic SASL mechanism name to the SPNEGO GSS-API mechanism, "SPNEGO". SASL client implementations MUST NOT choose the SPNEGO mechanism under any circumstances.

The GSS_C_MA_MECH_NEGO attribute of GSS_Inquire_attrs_for_mech (Williams, N., “Extended Generic Security Service Mechanism Inquiry APIs,” July 2009.) [RFC5587] can be used to identify such mechanisms.

16.  IANA Considerations

The IANA has registered a SASL mechanism family as per [RFC4422] (Melnikov, A. and K. Zeilenga, “Simple Authentication and Security Layer (SASL),” June 2006.) using the following information.

  Subject: Registration of SASL mechanism family GS2-*
  SASL mechanism prefix: GS2-
  Security considerations: RFC 5801
  Published specification: RFC 5801
  Person & email address to contact for further information:
    Simon Josefsson <simon@josefsson.org>
  Intended usage: COMMON
  Owner/Change controller: iesg@ietf.org
  Note: Compare with the GSSAPI and GSS-SPNEGO mechanisms.

The IANA is advised that SASL mechanism names starting with "GS2-" are reserved for SASL mechanisms that conform to this document. The IANA has placed a statement to that effect in the SASL Mechanisms registry.

The IANA is further advised that GS2 SASL mechanism names MUST NOT end in "-PLUS" except as a version of another mechanism name simply suffixed with "-PLUS".

The SASL names for the Kerberos V5 GSS-API mechanism [RFC4121] (Zhu, L., Jaganathan, K., and S. Hartman, “The Kerberos Version 5 Generic Security Service Application Program Interface (GSS-API) Mechanism: Version 2,” July 2005.) [RFC1964] (Linn, J., “The Kerberos Version 5 GSS-API Mechanism,” June 1996.) used via GS2 SHALL be "GS2-KRB5" and "GS2-KRB5-PLUS".

The SASL names for the SPNEGO GSS-API mechanism used via GS2 SHALL be "SPNEGO" and "SPNEGO-PLUS". As described in Section 15 (GSS-API Mechanisms That Negotiate Other Mechanisms), the SASL "SPNEGO" and "SPNEGO-PLUS" MUST NOT be used. These names are provided as a convenience for SASL library implementors.

17.  Security Considerations

Security issues are also discussed throughout this memo.

The security provided by a GS2 mechanism depends on the security of the GSS-API mechanism. The GS2 mechanism family depends on channel binding support, so GSS-API mechanisms that do not support channel binding cannot be successfully used as SASL mechanisms via the GS2 bridge.

Because GS2 does not support security layers, it is strongly RECOMMENDED that channel binding to a secure external channel be used. Successful channel binding eliminates the possibility of man-in-the-middle (MITM) attacks, provided that the external channel and its channel binding data are secure and that the GSS-API mechanism used is secure. Authentication failure because of channel binding failure may indicate that an MITM attack was attempted, but note that a real MITM attacker would likely attempt to close the connection to the client or simulate network partition; thus, MITM attack detection is heuristic.

Use of channel binding will also protect the SASL mechanism negotiation -- if there is no MITM, then the external secure channel will have protected the SASL mechanism negotiation.

The channel binding data MAY be sent (by the actual GSS-API mechanism used) without confidentiality protection and knowledge of it is assumed to provide no advantage to an MITM (who can, in any case, compute the channel binding data independently). If the external channel does not provide confidentiality protection and the GSS-API mechanism does not provide confidentiality protection for the channel binding data, then passive attackers (eavesdroppers) can recover the channel binding data, see [RFC5056] (Williams, N., “On the Use of Channel Bindings to Secure Channels,” November 2007.).

When constructing the input_name_string for GSS_Import_name with the GSS_C_NT_HOSTBASED_SERVICE name type, the client SHOULD NOT canonicalize the server's fully qualified domain name using an insecure or untrusted directory service, such as the Domain Name System (Mockapetris, P., “Domain names - concepts and facilities,” November 1987.) [RFC1034] without DNS Security (DNSSEC) (Arends, R., Austein, R., Larson, M., Massey, D., and S. Rose, “DNS Security Introduction and Requirements,” March 2005.) [RFC4033].

SHA-1 is used to derive SASL mechanism names, but no traditional cryptographic properties are required -- the required property is that the truncated output for distinct inputs are different for practical input values. GS2 does not use any other cryptographic algorithm. Therefore, GS2 is "algorithm agile", or, as agile as the GSS-API mechanisms that are available for use in SASL applications via GS2.

GS2 does not protect against downgrade attacks of channel binding types. Negotiation of channel binding type was intentionally left out of scope for this document.

The security considerations of SASL [RFC4422] (Melnikov, A. and K. Zeilenga, “Simple Authentication and Security Layer (SASL),” June 2006.), the GSS-API [RFC2743] (Linn, J., “Generic Security Service Application Program Interface Version 2, Update 1,” January 2000.), channel binding [RFC5056] (Williams, N., “On the Use of Channel Bindings to Secure Channels,” November 2007.), any external channels (such as TLS, [RFC5246] (Dierks, T. and E. Rescorla, “The Transport Layer Security (TLS) Protocol Version 1.2,” August 2008.), channel binding types (see the IANA channel binding type registry), and GSS-API mechanisms (such as the Kerberos V5 mechanism [RFC4121] (Zhu, L., Jaganathan, K., and S. Hartman, “The Kerberos Version 5 Generic Security Service Application Program Interface (GSS-API) Mechanism: Version 2,” July 2005.) [RFC1964] (Linn, J., “The Kerberos Version 5 GSS-API Mechanism,” June 1996.)), also apply.

18.  Acknowledgements

The history of GS2 can be traced to the "GSSAPI" mechanism originally specified by RFC 2222. This document was derived from draft-ietf-sasl-gssapi-02 which was prepared by Alexey Melnikov with significant contributions from John G. Myers, although the majority of this document has been rewritten by the current authors.

Contributions of many members of the SASL mailing list are gratefully acknowledged. In particular, ideas and feedback from Pasi Eronen, Sam Hartman, Jeffrey Hutzelman, Alexey Melnikov, and Tom Yu improved the document and the protocol. Other suggestions to the documents were made by Spencer Dawkins, Ralph Droms, Adrian Farrel, Robert Sparks, and Glen Zorn.

19.  References

19.1. Normative References

19.2. Informative References

Author's Address