Network Working Group N. Williams
Internet-Draft Cryptonector
Intended status: Informational December 15, 2012
Expires: June 18, 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 18, 2013.

Copyright Notice

Copyright (c) 2012 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.


Table of Contents

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;
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].

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

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:

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

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:

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;
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:

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.

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

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.

5. GSS-API Profile and Subset Identifiers

We define identifiers for GSS-API profiles and subsets. These should be used as follows:

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]

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.

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>

...

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.

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.

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

10. Informative References

[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, August 2008.
[RFC5056] Williams, N., "On the Use of Channel Bindings to Secure Channels", RFC 5056, November 2007.
[RFC5929] Altman, J., Williams, N. and L. Zhu, "Channel Bindings for TLS", RFC 5929, July 2010.
[RFC2743] Linn, J., "Generic Security Service Application Program Interface Version 2, Update 1", RFC 2743, January 2000.
[RFC5587] Williams, N., "Extended Generic Security Service Mechanism Inquiry APIs", RFC 5587, July 2009.
[RFC6680] Williams, N., Johansson, L., Hartman, S. and S. Josefsson, "Generic Security Service Application Programming Interface (GSS-API) Naming Extensions", RFC 6680, August 2012.
[RFC5588] Williams, N., "Generic Security Service Application Program Interface (GSS-API) Extension for Storing Delegated Credentials", RFC 5588, July 2009.
[RFC4401] Williams, N., "A Pseudo-Random Function (PRF) API Extension for the Generic Security Service Application Program Interface (GSS-API)", RFC 4401, February 2006.

Author's Address

Nicolas Williams Cryptonector, LLC EMail: nico@cryptonector.com