Simplified and Minimized Profiles of the Generic Security Services Application Programming Interface
Author(s): Nico Williams
The Generic Security Service Application Programming Interface (GSS- API) is often mistaken for a bloated framework. The GSS-API is really several things: a basis for formal descriptions of application authentication protocols (what happens when), a pattern for actual...
Network Working Group N. Williams Internet-Draft Cryptonector Intended status: Informational December 14, 2012 Expires: June 17, 2013 Simplified and Minimized Profiles of the Generic Security Services Application Programming Interface draft-williams-gss-profiles-00 Abstract The Generic Security Service Application Programming Interface (GSS- API) is often mistaken for a bloated framework. The GSS-API is really several things: a basis for formal descriptions of application authentication protocols (what happens when), a pattern for actual programming APIs, a set of constraints and requirements for generic security mechanisms, and concrete programming APIs. Only the first of these is relevant to Internet application protocols. This document describes simplified and minimized profiles of the GSS- API for two purposes: explaining its use, whether in standards specifications or actual applications, and specifying sub-sets of the API for a) newcomers to the API, b) application developers that wish to use it but not have to link the whole thing into their applications. 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 June 17, 2013. Copyright Notice Copyright (c) 2012 IETF Trust and the persons identified as the document authors. All rights reserved. Williams Expires June 17, 2013 [Page 1] Internet-Draft GSS-API Profiles December 2012 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. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. A Brief Primer on the GSS-API . . . . . . . . . . . . . . . 3 1.2. Conventions used in this document . . . . . . . . . . . . . 4 2. Simple Profiles of the GSS-API . . . . . . . . . . . . . . . 5 2.1. Trivial Initiator (client) Application . . . . . . . . . . . 5 2.2. Simple Initiator Application . . . . . . . . . . . . . . . . 6 2.3. Trivial Acceptor (server) Application . . . . . . . . . . . 6 2.4. Simple Acceptor Application . . . . . . . . . . . . . . . . 7 3. Transport Security Layer Profiles . . . . . . . . . . . . . 8 3.1. Null Transport Security . . . . . . . . . . . . . . . . . . 8 3.2. TLS with Server Name Binding . . . . . . . . . . . . . . . . 8 3.3. TLS with Channel Binding . . . . . . . . . . . . . . . . . . 8 3.4. Per-Message Tokens . . . . . . . . . . . . . . . . . . . . . 9 3.5. GSS-Keyed Application Transport Security Layer . . . . . . . 9 4. Complex Profiles . . . . . . . . . . . . . . . . . . . . . . 10 4.1. Advanced Initiator Application . . . . . . . . . . . . . . . 10 4.2. Advanced Acceptor Application . . . . . . . . . . . . . . . 10 5. GSS-API Profile and Subset Identifiers . . . . . . . . . . . 11 5.1. C-Bindings . . . . . . . . . . . . . . . . . . . . . . . . . 12 6. Mechanism Profiles . . . . . . . . . . . . . . . . . . . . . 13 6.1. Intranet Profile: SPNEGO, Kerberos . . . . . . . . . . . . . 13 6.2. Internet Profile: SPNEGO, <TBD> . . . . . . . . . . . . . . 13 7. Minimized GSS-API Implementations . . . . . . . . . . . . . 14 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . 15 9. Security Considerations . . . . . . . . . . . . . . . . . . 16 10. Informative References . . . . . . . . . . . . . . . . . . . 17 Author's Address . . . . . . . . . . . . . . . . . . . . . . 18 Williams Expires June 17, 2013 [Page 2] Internet-Draft GSS-API Profiles December 2012 1. Introduction There has been some confusion in the Internet community as to the nature of the GSS-API. One problem that has been identified by some is that the GSS-API is quite large, that simpler subsets of it may be desirable. This document proposes some subsets and "profiles" of the GSS-API. We hope this will make the API more approachable, acceptable, and easier to understand. The GSS-API is first and foremost an _abstract_ API whose purpose is to describe with high precision how Internet application protocols handle user/service authentication and transport security. The GSS-API is also a set of constraints on its security mechanisms. The GSS-API is also a pattern for programming language bindings of the abstract GSS-API. In the IETF we have standardized C and Java bindings for the abstract API. Note that there is _absolutely no requirement_ that implementators use the C or Java, or any other bindings of the GSS-API to implement applications whose specifications use the _abstract_ GSS-API. For example, one major implementor uses a different API (though in broad strokes quite similar to the GSS-API) to access generic security mechanisms, and applications using that API interoperate perfectly with applications that use bonafide GSS-API implementations. By providing minimized profiles/subsets of the GSS-API we hope to make the GSS-API easier to use. 1.1. A Brief Primer on the GSS-API In GSS terminology we have: Principals Entities to be authenticated; Credentials Credentials are used to authenticate principals; Security context tokens Messages exchanged by two principals to authenticate one to the other (and possibly the other to the one); Security contexts The shared state (e.g., session keys) that results from a successful exchange of security context tokens; Initiator The party (typically the client) that initiates a security context token exchange; Williams Expires June 17, 2013 [Page 3] Internet-Draft GSS-API Profiles December 2012 Acceptor The party (typically the server) that receives an initial security context token. The abstract API has a few data types: Buffers Octet strings; OIDs Constants identifying GSS mechanisms and name types; OID sets Sets of OIDs; NAME Opaque object representing the name of a principal; CREDENTIAL HANDLE Opaque object representing a credential for authenticating the entity that has access to it; SECURITY CONTEXT HANDLE Opaque object representing a security context. 1.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]. Williams Expires June 17, 2013 [Page 4] Internet-Draft GSS-API Profiles December 2012 2. Simple Profiles of the GSS-API We define profiles of the GSS-API for a variety of applications. These can be used both, for application security protocol specifications, and for implementation (but the latter is never required). o Trivial client ("initiator") applications; o Simple initiator applications; o Various security layer options; o Trivial server ("acceptor") applications; o Simple acceptor applications. We also define C bindings for these profiles, as well as for specific additional subsets of GSS-API functionality. These will take the form of C pre-processor macros indicating what profiles and functionality subsets are available. 2.1. Trivial Initiator (client) Application This profile requires just six GSS-API functions, three of which are destructors, and one of which is a function for formatting error strings: GSS_Import_name() Produces a NAME object given a string and a name type; GSS_Init_sec_context() Drives the exchange of security context tokens (authentication messages) on the initiator side; GSS_Display_status() Produces a human-readable representation of a status code (error code); destructor functions: o GSS_Release_name() o GSS_Release_buffer() o GSS_Delete_sec_context() The trivial initiator application profile REQUIRES two name-types: GSS_C_NT_HOSTBASED_SERVICE and GSS_C_NO_OID (denoting a mechanism- specific default name syntax). Williams Expires June 17, 2013 [Page 5] Internet-Draft GSS-API Profiles December 2012 A trivial initiator application begins by using GSS_Import_name() to get a NAME object for the target acceptor (server). This will be a host-based service name like "HTTP@hostname". The application then loops over GSS_Init_sec_context() to drive the exchange security context tokens (authentication messages) with the target. Most input arguments to GSS_Init_sec_context() will be defaulted. If a trivial initiator application has multiple initiator credentials to choose from then the choice of credential will be left to the GSS- API framework or security mechanism. GSS-API implementations SHOULD provide some facility for configuring reasonable initiator identity selection. 2.2. Simple Initiator Application This profile adds two functions to the trivial initiator application profile, one of which is a destructor: GSS_Acquire_cred() Produces a CREDENTIAL HANDLE for a given desired NAME. destructor function: o GSS_Release_cred() The initiator application may have multiple credentials and want to choose a specific one to authenticate as to a target. Such an application does so by calling GSS_Import_name() for the desired name, then GSS_Acquire_cred() to acquire a CREDENTIAL HANDLE to pass to GSS_Init_sec_context() as the initiator credential. 2.3. Trivial Acceptor (server) Application This profile requires just eight GSS-API functions, three of which are destructors, and one of which is a function for formatting error strings: GSS_Accept_sec_context() Driver of security context token exchange; GSS_Display_name_ext() Produces human-readable representation of a NAME object in the syntax of selected name type, if possible; GSS_Display_name() Produces a human-readable representation of a NAME object in a mechanism-specific syntax; Williams Expires June 17, 2013 [Page 6] Internet-Draft GSS-API Profiles December 2012 GSS_Export_name() Produces a machine-readable representation of a NAME object in a mechanism-specific format; GSS_Display_status() Produces a human-readable representation of a status code (error code); destructor functions: o GSS_Release_name() o GSS_Release_buffer() o GSS_Delete_sec_context() This profile REQUIRES one name-type: GSS_C_NT_USERNAME. A trivial acceptor application begins by using GSS_Accept_sec_context() to drive an exchange of security context tokens by which to authenticate an initiator. A successful authentication will yield a NAME representing the identity of the initiator - the acceptor will perform authorization based on the name of the initiator. The acceptor application MUST use one of GSS_Display_name_ext(), GSS_Display_name(), or GSS_Export_name() to obtain a textual or binary representation of the initiator name suitable for authorization. Most input arguments to GSS_Accept_sec_context() will be defaulted. If a trivial acceptor application has multiple acceptor credentials to choose from then the choice will be the initiator's. 2.4. Simple Acceptor Application This profile adds three functions to the trivial initiator application profile: GSS_Inquire_context() A simple acceptor application may be interested in knowing what name it was called by the initiator, and may do so by calling GSS_Inquire_context(). GSS_Store_cred() A simple acceptor application may have a use for delegated credentials. This function makes it possible to make delegated credentials available to other applications. GSS_Release_cred() This is the destructor for the delegated CREDENTIAL HANDLE. Williams Expires June 17, 2013 [Page 7] Internet-Draft GSS-API Profiles December 2012 3. Transport Security Layer Profiles Internet applications often require transport security - integrity protection or integrity and confidentiality protection. In simpler terms: some applications require encryption. The GSS-API was originally designed to provide facilities that the application could use to protect its in-flight data. Since then a number of options have been added to make it easier to use the GSS- API in existing applications that already have transport security facilities. The GSS-API now supports applications that use TLS for transport security, applications that have their own cryptographic transport protection facilities (like AFS' RX transport), as well as applications that can just use the original GSS-API transport security facilities. It is now possible to retrofit the GSS-API for authentication (and, where required, key exchange) into the widest possible range of applications. 3.1. Null Transport Security In some environments strong authentication of users and services is sufficient, with no need to protect in-flight data from passive nor active attacks. The trivial and simple profiles of the GSS-API suffice for these applications. 3.2. TLS with Server Name Binding This profile adds not functions to any of the trivial and simple acceptor application profiles. Applications using this profile use TLS [RFC5246] for transport security and the GSS-API for authentication. This profile REQUIRES that applications use the 'tls-server-end-point' channel binding type [RFC5929] a TLS server certificate to authenticate the server to the client and that the same server name used to authenticate the server in TLS also be used to authenticate the server in the GSS-API. 3.3. TLS with Channel Binding This profile adds no functions to any of the initiator or acceptor application profiles. Instead this profile makes support for channel binding [RFC5056] REQUIRED. Applications using this profile use TLS [RFC5246] for transport security, possibly using anonymous Diffie-Hellman (DH) cipher suites. Channel binding ensures that the end-points of the TLS connection are Williams Expires June 17, 2013 [Page 8] Internet-Draft GSS-API Profiles December 2012 logically the same as the GSS-API end-points, thus ensuring that there are no men in the middle (MITMs) even if anonymous DH TLS cipher suites are used. 3.4. Per-Message Tokens This profile adds four functions to the simple initiator application profile: GSS_GetMIC() Get an authentication code for a message (something like a MAC); GSS_VerifyMIC() Verify an authentication code sent by the peer; GSS_Wrap() Wrap an application message, typically to provide confidentiality and integrity protection (i.e., encrypt with authentication); GSS_Unwrap() Unwrap a wrapped application message (i.e., decrypt with authentication). An application of this type will rely on the GSS-API security mechanism to provide confidentiality and/or integrity protection to the application's messages. This kind of application typically does not use TLS or any other framework for transport security. Applications may use these functions to implement either of octet streams and unsequenced datagram security layers. 3.5. GSS-Keyed Application Transport Security Layer This profile adds one function to the simple initiator application profile: GSS_Pseudo_random() Get a pseudo-random output octet string based on session keys exchanged by the GSS-API security mechanism and an input octet string provided by the application. An application of this type typically has its own transport security layer (i.e., does its own encryption) and only requires a session key, which it can get from the GSS-API security context by using the GSS_Pseudo_random() [RFC4401] function to obtain an octet string of suitable length. Williams Expires June 17, 2013 [Page 9] Internet-Draft GSS-API Profiles December 2012 4. Complex Profiles 4.1. Advanced Initiator Application A complex initiator application requires most of the functions defined in [RFC5587] in addition to those of the simple initiator application profile: GSS_Indicate_mechs_by_attrs() Select mechanisms based on desired attributes; GSS_Inquire_attrs_for_mech() Get the set of attributes of a given mechanism. These functions are useful for mechanism negotiation. 4.2. Advanced Acceptor Application A complex acceptor application typically requires fine-grained access to the initiator names so as to implement more advanced authorization schemes. This means all of the naming extensions APIs: GSS_Display_name_ext() Already covered in Section 2.3. GSS_Inquire_name() Needed to list attributes available in the initiator name. GSS_Get_name_attribute() Needed to access individual attributes of the initiator name. GSS_Export_name_composite() Needed to be able to save a binary version of the initiator name with all its attributes. Complex acceptor applications may also need at least one extended mechanism inquiry function [RFC5587]: GSS_Inquire_attrs_for_mech() Get the set of attributes of a given mechanism. Williams Expires June 17, 2013 [Page 10] Internet-Draft GSS-API Profiles December 2012 5. GSS-API Profile and Subset Identifiers We define identifiers for GSS-API profiles and subsets. These should be used as follows: o Internet application specifications using the GSS-API must list the profiles/subsets of the API required to implement the specification; o GSS-API implementations SHOULD use these identifiers to advertise which profiles/subsets of the API are available o GSS-API application implementations using the GSS-API in the implementation SHOULD use these identifiers to request profiles/ subsets of the API to use. The identifiers are: GSS_PR_V2U1 This refers to the base GSS-API version 2 update 1. GSS_PR_TRIVIAL_INITIATOR See Section 2.1. GSS_PR_SIMPLE_INITIATOR See Section 2.2. GSS_PR_TRIVIAL_ACCEPTOR See Section 2.3. GSS_PR_SIMPLE_ACCEPTOR See Section 2.4. GSS_PR_ADVANCED_INITIATOR See Section 4.1. GSS_PR_ADVANCED_ACCEPTOR See Section 4.2. GSS_PR_CB See Section 3.3. GSS_PR_MSG_TOKENS See Section 3.4. GSS_PR_PRF See Section 3.5 [RFC4401]. GSS_PR_STORE_CRED See Section 2.4 and [RFC5588] GSS_PR_EXTENDED_MECH_INQUIRY Functions from [RFC5587] GSS_PR_EXTENDED_NAMING Functions from [RFC6680] Williams Expires June 17, 2013 [Page 11] Internet-Draft GSS-API Profiles December 2012 5.1. C-Bindings C pre-processor macros MUST be defined by <gssapi.h> or <gssapi/ gssapi.h> for each of the supported profiles and subsets of the GSS- API supported by the GSS-API implementation. The C pre-processor macro names MUST be as given in the preceding section, and the value should be 1 if the macro is defined. Williams Expires June 17, 2013 [Page 12] Internet-Draft GSS-API Profiles December 2012 6. Mechanism Profiles A mechanism profile is a set of GSS-API mechanisms that MUST be provided. 6.1. Intranet Profile: SPNEGO, Kerberos ... 6.2. Internet Profile: SPNEGO, <TBD> ... Williams Expires June 17, 2013 [Page 13] Internet-Draft GSS-API Profiles December 2012 7. Minimized GSS-API Implementations Typically a GSS-API implementation includes all of the basic version 2, update 1 API [RFC2743]. For embedded and mobile applications it may be desirable to have minimized GSS-API implementations, both for the framework itself and the mechanisms. A minimized implementation should provide at least the functionality required by the application and, preferably, no more than is required by the application. In practice this may mean that a complete implementation may have to provide tools for reducing the functionality provided. One possibility may be to implement a system whereby all the sources for a C implementation are combined into a single file and then C pre-processing can be used to eliminate all functionality that is not desired, then the resulting object file is linked into the application. This is known by some as an "amalgamation", and is much like static linking, but can be significantly more selective. This approach is used by SQLite3, for example. Another possibility is to structure the framework library and the mechanism plugins such that subsets are in distinct static linking archives or shared objects. This approach may result in a multiplicity of libraries and/or packages that reflect the profiles of the GSS-API. For minimization we recommend either the amalgamation approach or a scheme whereby static linking archives are used. For general purpose use we recommend dynamic linking and no minimization. Williams Expires June 17, 2013 [Page 14] Internet-Draft GSS-API Profiles December 2012 8. IANA Considerations We ask the IANA to create a registry of GSS-API profiles and subsets, with the identifiers list from of Section 5 as its contents. Williams Expires June 17, 2013 [Page 15] Internet-Draft GSS-API Profiles December 2012 9. Security Considerations The security considerations of the GSS-API version 2, update 1, and its various extensions apply. Using too trivial a profile for an application can have security impact. For example, applications using the trivial initiator application profile (GSS_PR_TRIVIAL_INITIATOR) cannot select an initiator identity and depend entirely on the framework and/or selected mechanism for this. Internet applications that use GSS mechanisms should specify one of th transport security layers from Section 3 other than the null layer as required to implement. The simplest transport security layer is, of course, none at all (see Section 3.1), but this is not secure in the Internet threat model; all the other options listed in Section 3 offer good security in the Internet threat model. The next simplest may well be to use TLS with server name binding (see Section 3.2). Williams Expires June 17, 2013 [Page 16] Internet-Draft GSS-API Profiles December 2012 10. Informative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC2119, March 1997. [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC5246, August 2008. [RFC5056] Williams, N., "On the Use of Channel Bindings to Secure Channels", RFC5056, November 2007. [RFC5929] Altman, J., Williams, N., and L. Zhu, "Channel Bindings for TLS", RFC5929, July 2010. [RFC2743] Linn, J., "Generic Security Service Application Program Interface Version 2, Update 1", RFC2743, January 2000. [RFC5587] Williams, N., "Extended Generic Security Service Mechanism Inquiry APIs", RFC5587, July 2009. [RFC6680] Williams, N., Johansson, L., Hartman, S., and S. Josefsson, "Generic Security Service Application Programming Interface (GSS-API) Naming Extensions", RFC6680, August 2012. [RFC5588] Williams, N., "Generic Security Service Application Program Interface (GSS-API) Extension for Storing Delegated Credentials", RFC5588, July 2009. [RFC4401] Williams, N., "A Pseudo-Random Function (PRF) API Extension for the Generic Security Service Application Program Interface (GSS-API)", RFC4401, February 2006. Williams Expires June 17, 2013 [Page 17] Internet-Draft GSS-API Profiles December 2012 Author's Address Nicolas Williams Cryptonector, LLC Email: email@example.com Williams Expires June 17, 2013 [Page 18]