One document matched: draft-williams-gss-profiles-00.xml

<?xml version="1.0" encoding="UTF-8"?>
<?rfc tocindent="no"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc toc="yes"?>
<?rfc symrefs="yes"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY rfc2119 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY rfc5246 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5246.xml">
<!ENTITY rfc5056 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5056.xml">
<!ENTITY rfc5929 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5929.xml">
<!ENTITY rfc2743 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2743.xml">
<!ENTITY rfc5587 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5587.xml">
<!ENTITY rfc6680 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6680.xml">
<!ENTITY rfc5588 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5588.xml">
<!ENTITY rfc4401 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4401.xml">
]>
<rfc docName="draft-williams-gss-profiles-00" ipr="trust200902" category="info">
  <front>
    <title abbrev="GSS-API Profiles">Simplified and Minimized Profiles of the Generic Security Services Application Programming Interface</title>
    <author initials="N." surname="Williams" fullname="Nicolas Williams">
      <organization abbrev="Cryptonector">Cryptonector, LLC</organization>
      <address>
        <email>nico@cryptonector.com</email>
      </address>
    </author>
    <date month="December" year="2012"/>
    <area>
Security Area
</area>
    <keyword>Internet-Draft</keyword>
    <abstract>
      <t>
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.</t>
      <t>
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.</t>
    </abstract>
  </front>
  <middle>
    <section title="Introduction" anchor="d1e295">
      <t>
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.</t>
      <t>
The GSS-API is first and foremost an <spanx>abstract</spanx>  API whose purpose is to describe with high precision how Internet application protocols handle user/service authentication and transport security.</t>
      <t>
The GSS-API is also a set of constraints on its security mechanisms.</t>
      <t>
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.</t>
      <t>
Note that there is <spanx>absolutely no requirement</spanx>  that implementators use the C or Java, or any other bindings of the GSS-API to implement applications whose specifications use the <spanx>abstract</spanx>  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.</t>
      <t>
By providing minimized profiles/subsets of the GSS-API we hope to make the GSS-API easier to use.</t>
      <section title="A Brief Primer on the GSS-API" anchor="d1e329">
        <t>
In GSS terminology we have:</t>
        <t>
          <list style="hanging">
            <t hangText="Principals">
 Entities to be authenticated;</t>
            <t hangText="Credentials">
 Credentials are used to authenticate principals;</t>
            <t hangText="Security context tokens">
 Messages exchanged by two principals to authenticate one to the other (and possibly the other to the one);</t>
            <t hangText="Security contexts">
 The shared state (e.g., session keys) that results from a successful exchange of security context tokens;</t>
            <t hangText="Initiator">
 The party (typically the client) that initiates a security context token exchange;</t>
            <t hangText="Acceptor">
 The party (typically the server) that receives an initial security context token.</t>
          </list>
        </t>
        <t>
The abstract API has a few data types:</t>
        <t>
          <list style="hanging">
            <t hangText="Buffers">
 Octet strings;</t>
            <t hangText="OIDs">
 Constants identifying GSS mechanisms and name types;</t>
            <t hangText="OID sets">
 Sets of OIDs;</t>
            <t hangText="NAME">
 Opaque object representing the name of a principal;</t>
            <t hangText="CREDENTIAL HANDLE">
 Opaque object representing a credential for authenticating the entity that has access to it;</t>
            <t hangText="SECURITY CONTEXT HANDLE">
 Opaque object representing a security context.</t>
          </list>
        </t>
      </section>
      <section title="Conventions used in this document" anchor="d1e405">
        <t>
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 <xref target="RFC2119"/>.</t>
      </section>
    </section>
    <section title="Simple Profiles of the GSS-API" anchor="d1e420">
      <t>
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).</t>
      <t>
        <list style="symbols">
          <t>
Trivial client (“initiator”) applications;</t>
          <t>
Simple initiator applications;</t>
          <t>
Various security layer options;</t>
          <t>
Trivial server (“acceptor”) applications;</t>
          <t>
Simple acceptor applications.</t>
        </list>
      </t>
      <t>
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.</t>
      <section title="Trivial Initiator (client) Application" anchor="sub_Trivial_Initiator">
        <t>
This profile requires just six GSS-API functions, three of which are destructors, and one of which is a function for formatting error strings:</t>
        <t>
          <list style="hanging">
            <t hangText="GSS_Import_name()">
 Produces a NAME object given a string and a name type;</t>
            <t hangText="GSS_Init_sec_context()">
 Drives the exchange of security context tokens (authentication messages) on the initiator side;</t>
            <t hangText="GSS_Display_status()">
 Produces a human-readable representation of a status code (error code);</t>
          </list>
        </t>
        <t>
destructor functions:</t>
        <t>
          <list style="symbols">
            <t>
GSS_Release_name()</t>
            <t>
GSS_Release_buffer()</t>
            <t>
GSS_Delete_sec_context()</t>
          </list>
        </t>
        <t>
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).</t>
        <t>
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.</t>
        <t>
Most input arguments to GSS_Init_sec_context() will be defaulted.</t>
        <t>
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.</t>
      </section>
      <section title="Simple Initiator Application" anchor="sub_Simple_Initiator">
        <t>
This profile adds two functions to the trivial initiator application profile, one of which is a destructor:</t>
        <t>
          <list style="hanging">
            <t hangText="GSS_Acquire_cred()">
 Produces a CREDENTIAL HANDLE for a given desired NAME.</t>
          </list>
        </t>
        <t>
destructor function:</t>
        <t>
          <list style="symbols">
            <t>
GSS_Release_cred()</t>
          </list>
        </t>
        <t>
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.</t>
      </section>
      <section title="Trivial Acceptor (server) Application" anchor="sub_Trivial_Acceptor">
        <t>
This profile requires just eight GSS-API functions, three of which are destructors, and one of which is a function for formatting error strings:</t>
        <t>
          <list style="hanging">
            <t hangText="GSS_Accept_sec_context()">
 Driver of security context token exchange;</t>
            <t hangText="GSS_Display_name_ext()">
 Produces human-readable representation of a NAME object in the syntax of selected name type, if possible;</t>
            <t hangText="GSS_Display_name()">
 Produces a human-readable representation of a NAME object in a mechanism-specific syntax;</t>
            <t hangText="GSS_Export_name()">
 Produces a machine-readable representation of a NAME object in a mechanism-specific format;</t>
            <t hangText="GSS_Display_status()">
 Produces a human-readable representation of a status code (error code);</t>
          </list>
        </t>
        <t>
destructor functions:</t>
        <t>
          <list style="symbols">
            <t>
GSS_Release_name()</t>
            <t>
GSS_Release_buffer()</t>
            <t>
GSS_Delete_sec_context()</t>
          </list>
        </t>
        <t>
This profile REQUIRES one name-type: GSS_C_NT_USERNAME.</t>
        <t>
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.</t>
        <t>
Most input arguments to GSS_Accept_sec_context() will be defaulted.</t>
        <t>
If a trivial acceptor application has multiple acceptor credentials to choose from then the choice will be the initiator's.</t>
      </section>
      <section title="Simple Acceptor Application" anchor="sub_Simple_Acceptor">
        <t>
This profile adds three functions to the trivial initiator application profile:</t>
        <t>
          <list style="hanging">
            <t hangText="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().</t>
            <t hangText="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.</t>
            <t hangText="GSS_Release_cred()">
 This is the destructor for the delegated CREDENTIAL HANDLE.</t>
          </list>
        </t>
      </section>
    </section>
    <section title="Transport Security Layer Profiles" anchor="sec_Transport_Security_Layer">
      <t>
Internet applications often require transport security – integrity protection or integrity and confidentiality protection. In simpler terms: some applications require encryption.</t>
      <t>
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.</t>
      <t>
It is now possible to retrofit the GSS-API for authentication (and, where required, key exchange) into the widest possible range of applications.</t>
      <section title="Null Transport Security" anchor="sub_Null_Transport_Security">
        <t>
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.</t>
      </section>
      <section title="TLS with Server Name Binding" anchor="sub_TLS_Name_Binding">
        <t>
This profile adds not functions to any of the trivial and simple acceptor application profiles.</t>
        <t>
Applications using this profile use TLS <xref target="RFC5246"/> for transport security and the GSS-API for authentication. This profile REQUIRES that applications use the 'tls-server-end-point' channel binding type <xref target="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.</t>
      </section>
      <section title="TLS with Channel Binding" anchor="sub_TLS_CB">
        <t>
This profile adds no functions to any of the initiator or acceptor application profiles. Instead this profile makes support for channel binding <xref target="RFC5056"/> REQUIRED.</t>
        <t>
Applications using this profile use TLS <xref target="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.</t>
      </section>
      <section title="Per-Message Tokens" anchor="sub_Per_msg_tokens">
        <t>
This profile adds four functions to the simple initiator application profile:</t>
        <t>
          <list style="hanging">
            <t hangText="GSS_GetMIC()">
 Get an authentication code for a message (something like a MAC);</t>
            <t hangText="GSS_VerifyMIC()">
 Verify an authentication code sent by the peer;</t>
            <t hangText="GSS_Wrap()">
 Wrap an application message, typically to provide confidentiality and integrity protection (i.e., encrypt with authentication);</t>
            <t hangText="GSS_Unwrap()">
 Unwrap a wrapped application message (i.e., decrypt with authentication).</t>
          </list>
        </t>
        <t>
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.</t>
        <t>
Applications may use these functions to implement either of octet streams and unsequenced datagram security layers.</t>
      </section>
      <section title="GSS-Keyed Application Transport Security Layer" anchor="sub_PRF">
        <t>
This profile adds one function to the simple initiator application profile:</t>
        <t>
          <list style="hanging">
            <t hangText="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.</t>
          </list>
        </t>
        <t>
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() <xref target="RFC4401"/> function to obtain an octet string of suitable length.</t>
      </section>
    </section>
    <section title="Complex Profiles" anchor="d1e765">
      <section title="Advanced Initiator Application" anchor="sub_Complex_Initiator_Application">
        <t>
A complex initiator application requires most of the functions defined in <xref target="RFC5587"/> in addition to those of the simple initiator application profile:</t>
        <t>
          <list style="hanging">
            <t hangText="GSS_Indicate_mechs_by_attrs()">
 Select mechanisms based on desired attributes;</t>
            <t hangText="GSS_Inquire_attrs_for_mech()">
 Get the set of attributes of a given mechanism.</t>
          </list>
        </t>
        <t>
These functions are useful for mechanism negotiation.</t>
      </section>
      <section title="Advanced Acceptor Application" anchor="sub_Complex_Acceptor_Application">
        <t>
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:</t>
        <t>
          <list style="hanging">
            <t hangText="GSS_Display_name_ext()">
 Already covered in  <xref target="sub_Trivial_Acceptor"/>.</t>
            <t hangText="GSS_Inquire_name()">
 Needed to list attributes available in the initiator name.</t>
            <t hangText="GSS_Get_name_attribute()">
 Needed to access individual attributes of the initiator name.</t>
            <t hangText="GSS_Export_name_composite()">
 Needed to be able to save a binary version of the initiator name with all its attributes.</t>
          </list>
        </t>
        <t>
Complex acceptor applications may also need at least one extended mechanism inquiry function <xref target="RFC5587"/>:</t>
        <t>
          <list style="hanging">
            <t hangText="GSS_Inquire_attrs_for_mech()">
 Get the set of attributes of a given mechanism.</t>
          </list>
        </t>
      </section>
    </section>
    <section title="GSS-API Profile and Subset Identifiers" anchor="sec_identifiers">
      <t>
We define identifiers for GSS-API profiles and subsets. These should be used as follows:</t>
      <t>
        <list style="symbols">
          <t>
Internet application specifications using the GSS-API must list the profiles/subsets of the API required to implement the specification;</t>
          <t>
GSS-API implementations SHOULD use these identifiers to advertise which profiles/subsets of the API are available</t>
          <t>
GSS-API application implementations using the GSS-API in the implementation SHOULD use these identifiers to request profiles/subsets of the API to use.</t>
        </list>
      </t>
      <t>
The identifiers are:</t>
      <t>
        <list style="hanging">
          <t hangText="GSS_PR_V2U1">
 This refers to the base GSS-API version 2 update 1.</t>
          <t hangText="GSS_PR_TRIVIAL_INITIATOR">
 See  <xref target="sub_Trivial_Initiator"/>.</t>
          <t hangText="GSS_PR_SIMPLE_INITIATOR">
 See  <xref target="sub_Simple_Initiator"/>.</t>
          <t hangText="GSS_PR_TRIVIAL_ACCEPTOR">
 See  <xref target="sub_Trivial_Acceptor"/>.</t>
          <t hangText="GSS_PR_SIMPLE_ACCEPTOR">
 See  <xref target="sub_Simple_Acceptor"/>.</t>
          <t hangText="GSS_PR_ADVANCED_INITIATOR">
 See  <xref target="sub_Complex_Initiator_Application"/>.</t>
          <t hangText="GSS_PR_ADVANCED_ACCEPTOR">
 See  <xref target="sub_Complex_Acceptor_Application"/>.</t>
          <t hangText="GSS_PR_CB">
 See  <xref target="sub_TLS_CB"/>.</t>
          <t hangText="GSS_PR_MSG_TOKENS">
 See  <xref target="sub_Per_msg_tokens"/>.</t>
          <t hangText="GSS_PR_PRF">
 See  <xref target="sub_PRF"/>
<xref target="RFC4401"/>.</t>
          <t hangText="GSS_PR_STORE_CRED">
 See  <xref target="sub_Simple_Acceptor"/> and <xref target="RFC5588"/>
</t>
          <t hangText="GSS_PR_EXTENDED_MECH_INQUIRY">
 Functions from <xref target="RFC5587"/>
</t>
          <t hangText="GSS_PR_EXTENDED_NAMING">
 Functions from <xref target="RFC6680"/>
</t>
        </list>
      </t>
      <section title="C-Bindings" anchor="d1e995">
        <t>
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.</t>
      </section>
    </section>
    <section title="Mechanism Profiles" anchor="d1e1005">
      <t>
A mechanism profile is a set of GSS-API mechanisms that MUST be provided.</t>
      <section title="Intranet Profile: SPNEGO, Kerberos" anchor="d1e1014">
        <t>
...</t>
      </section>
      <section title="Internet Profile: SPNEGO, <TBD>" anchor="d1e1023">
        <t>
...</t>
      </section>
    </section>
    <section title="Minimized GSS-API Implementations" anchor="d1e1032">
      <t>
Typically a GSS-API implementation includes all of the basic version 2, update 1 API <xref target="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.</t>
      <t>
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.</t>
      <t>
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.</t>
      <t>
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.</t>
    </section>
    <section title="IANA Considerations" anchor="d1e1057">
      <t>
We ask the IANA to create a registry of GSS-API profiles and subsets, with the identifiers list from of  <xref target="sec_identifiers"/> as its contents.</t>
    </section>
    <section title="Security Considerations" anchor="d1e1069">
      <t>
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.</t>
      <t>
Internet applications that use GSS mechanisms should specify one of th transport security layers from  <xref target="sec_Transport_Security_Layer"/> other than the null layer as required to implement. The simplest transport security layer is, of course, none at all (see  <xref target="sub_Null_Transport_Security"/>), but this is not secure in the Internet threat model; all the other options listed in  <xref target="sec_Transport_Security_Layer"/> offer good security in the Internet threat model. The next simplest may well be to use TLS with server name binding (see  <xref target="sub_TLS_Name_Binding"/>).</t>
    </section>
  </middle>
  <back>
    <references title="Informative References" anchor="d1e1093">&rfc2119;
&rfc5246;
&rfc5056;
&rfc5929;
&rfc2743;
&rfc5587;
&rfc6680;
&rfc5588;
&rfc4401;
</references>
  </back>
</rfc>