One document matched: draft-williams-kitten-ctx-simple-async-00.xml
<?xml version="1.0" encoding="UTF-8"?>
<?rfc toc="yes"?>
<?rfc symrefs="yes"?>
<?rfc tocindent="no"?>
<?rfc toc="yes"?>
<?rfc symrefs="yes"?>
<?rfc tocindent="no"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY rfc2119 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY rfc2743 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2743.xml">
<!ENTITY rfc2744 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2744.xml">
<!ENTITY rfc5056 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5056.xml">
<!ENTITY rfc5587 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5587.xml">
<!ENTITY rfc5653 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5653.xml">
]>
<rfc docName="draft-williams-kitten-ctx-simple-async-00" ipr="trust200902" category="std" updates="2743, 2744">
<front>
<title abbrev="Simple GSS">Simplified and Asynchronous Security Context Interfaces for 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="July" year="2013"/>
<area>
Security Area
</area>
<keyword>Internet-Draft</keyword>
<abstract>
<t>
This Internet-Draft proposes extensions to the Generic Security Services Application Programming Interface (GSS-API) for replacing the exiting GSS_Init_sec_context() and GSS_Accept_sec_context() functions with simplified forms that also support asynchrony.</t>
</abstract>
</front>
<middle>
<section title="Introduction" anchor="d1e329">
<t>
We propose replacing the GSS_Init_sec_context() and GSS_Accept_sec_context() functions with a set of simpler functions: one to create an “empty” security context, a set of functions to set context parameters, a single function for “stepping” the security context token exchange, and additional security context inquiry functions. Support for non-blocking stepping of security context token exchange is also included.</t>
<section title="Channel Binding Semantics Improvements" anchor="d1e338">
<t>
The extensions specified in this document are a further extension to <xref target="I-D.williams-kitten-channel-bound-flag"/>.</t>
</section>
<section title="Conventions used in this document" anchor="d1e354">
<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="Simplified API" anchor="d1e369">
<t>
We add a function for creating “empty” security contexts:</t>
<t>
<list style="symbols">
<t>
GSS_Create_sec_context()</t>
</list>
</t>
<t>
We add the following new mutator functions for empty security contexts:</t>
<t>
<list style="symbols">
<t>
GSS_Set_context_flags()</t>
<t>
GSS_Set_context_credentials()</t>
<t>
GSS_Set_context_role_init()</t>
<t>
GSS_Set_context_channel_bindings()</t>
<t>
GSS_Set_context_lifetime()</t>
<t>
GSS_Set_async_IO_notification()</t>
<t>
GSS_Set_async_event_loop()</t>
</list>
</t>
<t>
We add a function for stepping through security context token exchanges:</t>
<t>
<list style="symbols">
<t>
GSS_Step_context()</t>
</list>
</t>
<t>
We add a function for retrieving delegated credentials from a security context token:</t>
<t>
<list style="symbols">
<t>
GSS_Get_context_deleg_cred()</t>
</list>
</t>
<section title="GSS_Create_sec_context()" anchor="d1e422">
<t>
Inputs:</t>
<t>
<list style="symbols">
<t>
<none></t>
</list>
</t>
<t>
Outputs:</t>
<t>
<list style="symbols">
<t>
major_status INTEGER</t>
<t>
minor_status INTEGER -- note: mostly useless, but we should keep it</t>
<t>
context SECURITY CONTEXT</t>
</list>
</t>
<t>
Return major status codes:</t>
<t>
<list style="symbols">
<t>
GSS_S_COMPLETE indicates success.</t>
<t>
GSS_S_UNAVAILABLE indicates that memory is not available, for example.</t>
<t>
GSS_S_FAILURE indicates a general failure.</t>
</list>
</t>
<t>
This function creates an “empty” security context handle that can be passed to GSS_Init_sec_context() or GSS_Accept_sec_context() where they expect a NULL context. The context can also be passed to the other new security context functions defined in this document.</t>
<section title="C-Bindings" anchor="d1e464">
<t>
</t>
<t>
<figure suppress-title="true" align="center">
<artwork> OM_uint32
gss_create_sec_context(OM_uint32 *minor_status,
gss_ctx_id_t *context);</artwork>
</figure>
</t>
</section>
</section>
<section title="GSS_Set_context_flags()" anchor="d1e477">
<t>
Inputs:</t>
<t>
<list style="hanging">
<t hangText="context CONTEXT HANDLE">
</t>
<t hangText="req_flags FLAGS">
Requested flags. Applicable to acceptors and initiators.</t>
<t hangText="ret_flags_understood FLAGS">
Return flags understood by the caller.</t>
</list>
</t>
<t>
Outputs:</t>
<t>
<list style="symbols">
<t>
major_status INTEGER</t>
<t>
minor_status INTEGER</t>
</list>
</t>
<t>
Return major status codes:</t>
<t>
<list style="symbols">
<t>
GSS_S_COMPLETE indicates success.</t>
<t>
GSS_S_FAILURE indicates a general failure.</t>
</list>
</t>
<t>
This function tells the mechanism (when one is eventually chosen and invoked) that the application requests the given req_flags and undestands the given ret_flags. Initiators can override the req_flags in their GSS_Init_sec_context() call, but if no flags are requested there then the req_flags set on the empty context will be used.</t>
<t>
NOTE: The abstract GSS-API <xref target="RFC2743"/> uses individual elements -one per-flag- instead of a “FLAGS” type. This is unwieldy, therefore we introduce an abstract type named “FLAGS” to act as a set of all the request/return flags defined for the abstract GSS-API.</t>
<section title="C-Bindings" anchor="d1e534">
<t>
</t>
<t>
<figure suppress-title="true" align="center">
<artwork> OM_uint32
gss_set_context_flags(OM_uint32 *minor_status,
gss_ctx_id_t context,
uint64_t req_flags,
uint64_t ret_flags);</artwork>
</figure>
</t>
</section>
</section>
<section title="GSS_Set_context_credentials()" anchor="d1e547">
<t>
Inputs:</t>
<t>
<list style="hanging">
<t hangText="context CONTEXT HANDLE">
Empty security context</t>
<t hangText="input_cred_handle CREDENTIAL HANDLE">
MUST NOT be the default credential.</t>
</list>
</t>
<t>
Outputs:</t>
<t>
<list style="symbols">
<t>
major_status INTEGER</t>
<t>
minor_status INTEGER</t>
</list>
</t>
<t>
Return major status codes:</t>
<t>
<list style="symbols">
<t>
GSS_S_COMPLETE indicates success.</t>
<t>
...</t>
<t>
GSS_S_FAILURE indicates a general failure.</t>
</list>
</t>
<t>
This function sets the application's credentials. If no credentials are set then the default credentials will be used.</t>
<t>
Multiple credentials may be set on a security context. The mechanism SHOULD allow accepting security contexts for any principals for which credentials had elements for the mechanism used. The mechanism SHOULD allow initiators to have multiple credentials, in which case the mechanism should select the credential most likely to succeed for the given target principal. Where a mechanism does not support multiple credentials it MUST use the first credential handle set by the application.</t>
<section title="C-Bindings" anchor="d1e596">
<t>
</t>
<t>
<figure suppress-title="true" align="center">
<artwork> OM_uint32
gss_set_context_credentials(OM_uint32 *minor_status,
gss_ctx_id_t context,
gss_const_cred_id_t input_cred_handle);</artwork>
</figure>
</t>
</section>
</section>
<section title="GSS_Set_context_channel_bindings()" anchor="d1e609">
<t>
Inputs:</t>
<t>
<list style="hanging">
<t hangText="context CONTEXT HANDLE">
Empty security context</t>
<t hangText="input_channel_bindings OCTET STRING">
</t>
</list>
</t>
<t>
Outputs:</t>
<t>
<list style="symbols">
<t>
major_status INTEGER</t>
<t>
minor_status INTEGER</t>
</list>
</t>
<t>
Return major status codes:</t>
<t>
<list style="symbols">
<t>
GSS_S_COMPLETE indicates success.</t>
<t>
...</t>
<t>
GSS_S_FAILURE indicates a general failure.</t>
</list>
</t>
<section title="C-Bindings" anchor="d1e652">
<t>
</t>
<t>
<figure suppress-title="true" align="center">
<artwork> OM_uint32
gss_set_context_channel_bindings(OM_uint32 *minor_status,
gss_ctx_id_t context,
gss_const_buffer_t input_cb);</artwork>
</figure>
</t>
</section>
</section>
<section title="GSS_Set_context_lifetime()" anchor="d1e665">
<t>
Inputs:</t>
<t>
<list style="hanging">
<t hangText="context CONTEXT HANDLE">
Empty security context</t>
<t hangText="lifetime_req INTEGER">
...</t>
</list>
</t>
<t>
Outputs:</t>
<t>
<list style="symbols">
<t>
major_status INTEGER</t>
<t>
minor_status INTEGER</t>
</list>
</t>
<t>
Return major status codes:</t>
<t>
<list style="symbols">
<t>
GSS_S_COMPLETE indicates success.</t>
<t>
...</t>
<t>
GSS_S_FAILURE indicates a general failure.</t>
</list>
</t>
<section title="C-Bindings" anchor="d1e708">
<t>
</t>
<t>
<figure suppress-title="true" align="center">
<artwork> OM_uint32
gss_set_context_lifetime(OM_uint32 *minor_status,
gss_ctx_id_t context,
uint64_t lifetime_req);</artwork>
</figure>
</t>
</section>
</section>
<section title="GSS_Set_async_IO_notification()" anchor="d1e721">
<t>
Inputs:</t>
<t>
<list style="hanging">
<t hangText="context CONTEXT HANDLE">
Empty security context</t>
<t hangText="async_notification_method UNSPECIFIED">
</t>
</list>
</t>
<t>
Outputs:</t>
<t>
<list style="symbols">
<t>
major_status INTEGER</t>
<t>
minor_status INTEGER</t>
</list>
</t>
<t>
Return major status codes:</t>
<t>
<list style="symbols">
<t>
GSS_S_COMPLETE indicates success.</t>
<t>
...</t>
<t>
GSS_S_FAILURE indicates a general failure.</t>
</list>
</t>
<t>
This function sets a method for informing the application that the given security context is ready to have GSS_Step_context() called on it. Whenever GSS_Step_context() returns GSS_S_CONTINUE_NEEDED and no output token the application must wait for the async I/O completion notification and then call GSS_Step_context() again (this time with no input token). GSS_Step_context() will only work asynchronously when this function has been used to set a completion notification method.</t>
<t>
The async I/O completion notification method is not specified for the abstract API. In the C bindings we allow for several different notification methods, including:</t>
<t>
<list style="symbols">
<t>
callback function</t>
<t>
file descriptor or file handle into which a single byte (of any value) will be written</t>
<t>
a condition variable (and associated mutex) on which a signal will be sent</t>
</list>
</t>
<t>
Other completion notification methods could be specified as well, but these seem likely to be sufficient and reasonably portable.</t>
<section title="C-Bindings" anchor="d1e784">
<t>
</t>
<t>
<figure suppress-title="true" align="center">
<artwork> typedef void (*gss_async_cb_t)(gss_ctx_id_t context, void *cb_data);
OM_uint32
gss_set_context_async_io_cb(OM_uint32 *minor_status,
gss_ctx_id_t context,
gss_async_cb_t cb,
void *cb_data);
#ifdef HAVE_POSIX
OM_uint32
gss_set_context_async_io_fd(OM_uint32 *minor_status,
gss_ctx_id_t context,
int fd);
#endif /* HAVE_POSIX */
#ifdef HAVE_WIN32
OM_uint32
gss_set_context_async_io_handle(OM_uint32 *minor_status,
gss_ctx_id_t context,
HANDLE h);
#endif /* HAVE_WIN32 */
#ifdef HAVE_PTHREADS
#include <pthread.h>
OM_uint32
gss_set_context_async_io_condvar(OM_uint32 *minor_status,
gss_ctx_id_t context,
pthread_cond_t cv,
pthread_mutex_t lock);
#endif /* HAVE_PTHREADS */
#ifdef HAVE_WIN32
#include <windows.h>
#include <stdlib.h> #include <stdio.h>
OM_uint32
gss_set_context_async_io_condvar(OM_uint32 *minor_status,
gss_ctx_id_t context,
CONDITION_VARIABLE cv,
CRITICAL_SECTION lock);
#endif /* HAVE_WIN32 */</artwork>
</figure>
</t>
</section>
</section>
<section title="GSS_Set_event_loop()" anchor="d1e796">
<t>
Inputs:</t>
<t>
<list style="hanging">
<t hangText="context CONTEXT HANDLE">
Empty security context</t>
<t hangText="event_loop_type INTEGER">
Type of event loop</t>
<t hangText="event_loop UNSPECIFIED">
An event loop</t>
<t hangText="event_loop_module UNSPECIFIED">
A module implementing the interface of the given event loop type</t>
</list>
</t>
<t>
Outputs:</t>
<t>
<list style="symbols">
<t>
major_status INTEGER</t>
<t>
minor_status INTEGER</t>
</list>
</t>
<t>
Return major status codes:</t>
<t>
<list style="symbols">
<t>
GSS_S_COMPLETE indicates success.</t>
<t>
...</t>
<t>
GSS_S_FAILURE indicates a general failure.</t>
</list>
</t>
<t>
This function sets an event loop to use by the mechanism. We specify no event loop interfaces here. Instead we allow for the use of existing event loop APIs.</t>
<t>
The following event loop types are defined (but not their interfaces):</t>
<t>
<list style="symbols">
<t>
EV_NONE (the mechanism MAY run a private event loop in a background thread, but only if the application also set a completion notification method);</t>
<t>
EV_LIBVERTO <eref target="https://fedorahosted.org/libverto/"/>;</t>
<t>
EV_LIBEVENT <eref target="http://libevent.org/"/>
</t>
<t>
EV_LIBEV <eref target="http://software.schmorp.de/pkg/libev.html"/>
</t>
<t>
EV_GLIB <eref target="http://developer.gnome.org/glib/stable/"/>
</t>
<t>
EV_TEVENT <eref target="http://tevent.samba.org/"/>
</t>
<t>
EV_GCD <eref target="https://libdispatch.macosforge.org/"/>
</t>
</list>
</t>
<t>
Asynchronous security context stepping is OPTIONAL. It is RECOMMENDED that mechanisms implement EV_LIBVERTO. Note that if the application's choice of event loop is not supported by a mechanism then GSS_Step_context() will return GSS_S_UNAVAILABLE_EVENT_LOOP_TYPE, in which case the application may try another event loop type, likely EV_NONE.</t>
<t>
An event loop module is a handle to a library implementing the interfaces of the given event loop type; the mechanism can obtain those interfaces (e.g., as function pointers in the C bindings). Event loops and modules are unspecified in the abstract API, but the intention is that the application passes to the mechanism a handle to the module implementing the chosen event loop interfaces.</t>
<section title="C-Bindings" anchor="d1e902">
<t>
</t>
<t>
<figure suppress-title="true" align="center">
<artwork> typedef enum {
EV_NONE = 1,
EV_LIBVERTO = 2,
EV_LIBEVENT = 4,
EV_LIBEV = 8,
EV_GLIB = 16,
EV_TEVENT = 32,
EV_GCD = 64
} gss_event_loop_type_t;
typedef void *(*gss_dlsym_t)(void *, const char *);
OM_uint32
gss_set_context_event_loop(OM_uint32 *minor_status,
gss_ctx_id_t context,
gss_event_loop_type_t event_loop_type,
void *event_loop,
gss_event_module_type_t event_module_type,
void *event_module,
gss_dlsym_t module_lookup);</artwork>
</figure>
</t>
</section>
</section>
<section title="GSS_Indicate_event_loop_types()" anchor="d1e914">
<t>
Inputs:</t>
<t>
<list style="hanging">
<t hangText="input_cred_handle CREDENTIAL HANDLE">
May be GSS_C_NO_CREDENTIAL</t>
</list>
</t>
<t>
Outputs:</t>
<t>
<list style="symbols">
<t>
major_status INTEGER</t>
<t>
minor_status INTEGER</t>
<t>
event_loop_types SET OF INTEGER</t>
</list>
</t>
<t>
Return major status codes:</t>
<t>
<list style="symbols">
<t>
GSS_S_COMPLETE indicates success.</t>
<t>
GSS_S_FAILURE indicates a general failure.</t>
</list>
</t>
<t>
This function indicates what event loop types are supported the mechanisms for the given credentials handle.</t>
<section title="C-Bindings" anchor="d1e956">
<t>
</t>
<t>
<figure suppress-title="true" align="center">
<artwork> OM_uint32
gss_indicate_event_loop_types(OM_uint32 *minor_status,
gss_cred_id_t input_cred_handle,
gss_event_loop_type_t *ev_types);</artwork>
</figure>
</t>
</section>
</section>
<section title="GSS_Set_context_role_init()" anchor="sub_GSS_Set_context_role_init__">
<t>
Inputs:</t>
<t>
<list style="hanging">
<t hangText="context CONTEXT HANDLE">
Empty security context handle</t>
<t hangText="mech_type OID">
Mechanism OID</t>
<t hangText="target_name NAME">
Name of target principal</t>
</list>
</t>
<t>
Outputs:</t>
<t>
<list style="symbols">
<t>
major_status INTEGER</t>
<t>
minor_status INTEGER</t>
<t>
event_loop_types SET OF INTEGER</t>
</list>
</t>
<t>
Return major status codes:</t>
<t>
<list style="symbols">
<t>
GSS_S_COMPLETE indicates success.</t>
<t>
...</t>
<t>
GSS_S_FAILURE indicates a general failure.</t>
</list>
</t>
<t>
This function sets the security context role to be that of an initiator, with the given mechanism OID (possibly GSS_C_NO_OID), and the given target name (possibly GSS_C_NO_NAME). The difference between an initiator and an acceptor application is that an initiator application calls this function and an acceptor does not; both call GSS_Step_context() (see Section 2.8). </t>
<section title="C-Bindings" anchor="d1e1025">
<t>
</t>
<t>
<figure suppress-title="true" align="center">
<artwork> OM_uint32
gss_set_context_context_role_init(OM_uint32 *minor_status,
gss_ctx_id_t context,
gss_const_OID mech_oid,
gss_const_name_t target_name); </artwork>
</figure>
</t>
</section>
</section>
<section title="GSS_Step_context()" anchor="sub_GSS_Step_context__">
<t>
Inputs:</t>
<t>
<list style="hanging">
<t hangText="context CONTEXT HANDLE">
Empty security context</t>
<t hangText="input_token OCTET STRING">
Input security context token, if any</t>
</list>
</t>
<t>
Outputs:</t>
<t>
<list style="symbols">
<t>
major_status INTEGER</t>
<t>
minor_status INTEGER</t>
<t>
output_token OCTET STRING -- output security context token, if any</t>
<t>
actual_mech OID -- OID of mechanism used</t>
</list>
</t>
<t>
Return major status codes:</t>
<t>
<list style="symbols">
<t>
GSS_S_COMPLETE indicates success.</t>
<t>
GSS_S_CONTINUE_NEEDED ...</t>
<t>
GSS_S_UNAVAILABLE_EVENT_LOOP_TYPE indicates that the application's choice of event loop type is not supported. The mechanism will have done no work in this case, and the application must change the event loop and try again.</t>
<t>
All major status codes allowed for GSS_Init_sec_context() and GSS_Accept_sec_context().</t>
<t>
GSS_S_FAILURE indicates a general failure.</t>
</list>
</t>
<t>
This function steps through one step of security context token exchange for the given security context.</t>
<t>
Acceptors call this without having called GSS_Set_context_role_init(); see <xref target="sub_GSS_Set_context_role_init__"/>.</t>
<t>
Note that if GSS_S_CONTINUE_NEEDED is returned but no security context is output, then the function must be called again upon async I/O completion notification.</t>
<section title="C-Bindings" anchor="d1e1107">
<t>
</t>
<t>
<figure suppress-title="true" align="center">
<artwork> OM_uint32
gss_step_context(OM_uint32 *minor_status,
gss_ctx_id_t context,
gss_const_buffer_t input_token,
gss_buffer_t output_token,
gss_const_OID *actual_mech);</artwork>
</figure>
</t>
</section>
</section>
</section>
<section title="Security Considerations" anchor="d1e1119">
<t>
The GSS-API is a security API, however, this document does not modify its semantics in any security-relevant way. There are no security considerations in this document.</t>
</section>
<section title="IANA Considerations" anchor="d1e1129">
<t>
[Add registrations for all the above functions.]</t>
</section>
</middle>
<back>
<references title="Normative References">&rfc2119;
&rfc2743;
&rfc2744;
&rfc5056;
&rfc5587;
<reference anchor="I-D.williams-kitten-channel-bound-flag"><front><title>Channel Binding Signalling for the Generic Security Services Application Programming Interface</title><author initials="N." surname="Williams" fullname="Nicolas Williams"><organization/></author><date month="February" day="13" year="2013"/><abstract><t>Abstract Channel binding is a technique that allows applications to use a secure channel at a lower layer without having to use authentication at that lower layer. The concept of channel binding comes from RFC2743 and its predecessors. It turns out that the semantics implemented are different that those specified in RFC2743, and the specification has a serious bug. This document addresses both, the inconsistency as-implemented and the specification bug.</t><t>Abstract This Internet-Draft proposes the addition of a “channel bound” return flag for the GSS_Init_sec_context() and GSS_Accept_sec_context() functions. Two behaviors are specified: a default, safe behavior, and a behavior that is only safe when the application specifically tells the Generic Security Services Application Programming Interface (GSS-API) that it (the applicaiton) supports the new behavior.</t></abstract></front><seriesInfo name="Internet-Draft" value="draft-williams-kitten-channel-bound-flag-02"/><format type="TXT" target="http://www.ietf.org/internet-drafts/draft-williams-kitten-channel-bound-flag-02.txt"/></reference> </references>
<references title="Informative References">&rfc5653;</references>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-24 08:53:38 |