Internet DRAFT - draft-williams-kitten-ctx-simple-async
draft-williams-kitten-ctx-simple-async
Network Working Group N. Williams
Internet-Draft Cryptonector
Updates: 2743, 2744 (if approved) July 7, 2013
Intended status: Standards Track
Expires: January 8, 2014
Simplified and Asynchronous Security Context Interfaces for the Generic
Security Services Application Programming Interface
draft-williams-kitten-ctx-simple-async-00
Abstract
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.
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 January 8, 2014.
Copyright Notice
Copyright (c) 2013 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
Williams Expires January 8, 2014 [Page 1]
Internet-Draft Simple GSS July 2013
described in the Simplified BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Channel Binding Semantics Improvements . . . . . . . . . . 3
1.2. Conventions used in this document . . . . . . . . . . . . 3
2. Simplified API . . . . . . . . . . . . . . . . . . . . . . 4
2.1. GSS_Create_sec_context() . . . . . . . . . . . . . . . . . 4
2.1.1. C-Bindings . . . . . . . . . . . . . . . . . . . . . . . . 5
2.2. GSS_Set_context_flags() . . . . . . . . . . . . . . . . . 5
2.2.1. C-Bindings . . . . . . . . . . . . . . . . . . . . . . . . 6
2.3. GSS_Set_context_credentials() . . . . . . . . . . . . . . 6
2.3.1. C-Bindings . . . . . . . . . . . . . . . . . . . . . . . . 7
2.4. GSS_Set_context_channel_bindings() . . . . . . . . . . . . 7
2.4.1. C-Bindings . . . . . . . . . . . . . . . . . . . . . . . . 7
2.5. GSS_Set_context_lifetime() . . . . . . . . . . . . . . . . 7
2.5.1. C-Bindings . . . . . . . . . . . . . . . . . . . . . . . . 8
2.6. GSS_Set_async_IO_notification() . . . . . . . . . . . . . 8
2.6.1. C-Bindings . . . . . . . . . . . . . . . . . . . . . . . . 9
2.7. GSS_Set_event_loop() . . . . . . . . . . . . . . . . . . . 10
2.7.1. C-Bindings . . . . . . . . . . . . . . . . . . . . . . . . 12
2.8. GSS_Indicate_event_loop_types() . . . . . . . . . . . . . 12
2.8.1. C-Bindings . . . . . . . . . . . . . . . . . . . . . . . . 13
2.9. GSS_Set_context_role_init() . . . . . . . . . . . . . . . 13
2.9.1. C-Bindings . . . . . . . . . . . . . . . . . . . . . . . . 14
2.10. GSS_Step_context() . . . . . . . . . . . . . . . . . . . . 14
2.10.1. C-Bindings . . . . . . . . . . . . . . . . . . . . . . . . 15
3. Security Considerations . . . . . . . . . . . . . . . . . 16
4. IANA Considerations . . . . . . . . . . . . . . . . . . . 17
5. References . . . . . . . . . . . . . . . . . . . . . . . . 18
5.1. Normative References . . . . . . . . . . . . . . . . . . . 18
5.2. Informative References . . . . . . . . . . . . . . . . . . 18
Author's Address . . . . . . . . . . . . . . . . . . . . . 19
Williams Expires January 8, 2014 [Page 2]
Internet-Draft Simple GSS July 2013
1. Introduction
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.
1.1. Channel Binding Semantics Improvements
The extensions specified in this document are a further extension to
[I-D.williams-kitten-channel-bound-flag].
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 January 8, 2014 [Page 3]
Internet-Draft Simple GSS July 2013
2. Simplified API
We add a function for creating "empty" security contexts:
o GSS_Create_sec_context()
We add the following new mutator functions for empty security
contexts:
o GSS_Set_context_flags()
o GSS_Set_context_credentials()
o GSS_Set_context_role_init()
o GSS_Set_context_channel_bindings()
o GSS_Set_context_lifetime()
o GSS_Set_async_IO_notification()
o GSS_Set_async_event_loop()
We add a function for stepping through security context token
exchanges:
o GSS_Step_context()
We add a function for retrieving delegated credentials from a
security context token:
o GSS_Get_context_deleg_cred()
2.1. GSS_Create_sec_context()
Inputs:
o <none>
Outputs:
o major_status INTEGER
o minor_status INTEGER -- note: mostly useless, but we should keep
it
o context SECURITY CONTEXT
Williams Expires January 8, 2014 [Page 4]
Internet-Draft Simple GSS July 2013
Return major status codes:
o GSS_S_COMPLETE indicates success.
o GSS_S_UNAVAILABLE indicates that memory is not available, for
example.
o GSS_S_FAILURE indicates a general failure.
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.
2.1.1. C-Bindings
OM_uint32
gss_create_sec_context(OM_uint32 *minor_status,
gss_ctx_id_t *context);
2.2. GSS_Set_context_flags()
Inputs:
context CONTEXT HANDLE
req_flags FLAGS Requested flags. Applicable to acceptors and
initiators.
ret_flags_understood FLAGS Return flags understood by the caller.
Outputs:
o major_status INTEGER
o minor_status INTEGER
Return major status codes:
o GSS_S_COMPLETE indicates success.
o GSS_S_FAILURE indicates a general failure.
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
Williams Expires January 8, 2014 [Page 5]
Internet-Draft Simple GSS July 2013
used.
NOTE: The abstract GSS-API [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.
2.2.1. C-Bindings
OM_uint32
gss_set_context_flags(OM_uint32 *minor_status,
gss_ctx_id_t context,
uint64_t req_flags,
uint64_t ret_flags);
2.3. GSS_Set_context_credentials()
Inputs:
context CONTEXT HANDLE Empty security context
input_cred_handle CREDENTIAL HANDLE MUST NOT be the default
credential.
Outputs:
o major_status INTEGER
o minor_status INTEGER
Return major status codes:
o GSS_S_COMPLETE indicates success.
o ...
o GSS_S_FAILURE indicates a general failure.
This function sets the application's credentials. If no credentials
are set then the default credentials will be used.
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
Williams Expires January 8, 2014 [Page 6]
Internet-Draft Simple GSS July 2013
the application.
2.3.1. C-Bindings
OM_uint32
gss_set_context_credentials(OM_uint32 *minor_status,
gss_ctx_id_t context,
gss_const_cred_id_t input_cred_handle);
2.4. GSS_Set_context_channel_bindings()
Inputs:
context CONTEXT HANDLE Empty security context
input_channel_bindings OCTET STRING
Outputs:
o major_status INTEGER
o minor_status INTEGER
Return major status codes:
o GSS_S_COMPLETE indicates success.
o ...
o GSS_S_FAILURE indicates a general failure.
2.4.1. C-Bindings
OM_uint32
gss_set_context_channel_bindings(OM_uint32 *minor_status,
gss_ctx_id_t context,
gss_const_buffer_t input_cb);
2.5. GSS_Set_context_lifetime()
Inputs:
context CONTEXT HANDLE Empty security context
lifetime_req INTEGER ...
Outputs:
Williams Expires January 8, 2014 [Page 7]
Internet-Draft Simple GSS July 2013
o major_status INTEGER
o minor_status INTEGER
Return major status codes:
o GSS_S_COMPLETE indicates success.
o ...
o GSS_S_FAILURE indicates a general failure.
2.5.1. C-Bindings
OM_uint32
gss_set_context_lifetime(OM_uint32 *minor_status,
gss_ctx_id_t context,
uint64_t lifetime_req);
2.6. GSS_Set_async_IO_notification()
Inputs:
context CONTEXT HANDLE Empty security context
async_notification_method UNSPECIFIED
Outputs:
o major_status INTEGER
o minor_status INTEGER
Return major status codes:
o GSS_S_COMPLETE indicates success.
o ...
o GSS_S_FAILURE indicates a general failure.
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
Williams Expires January 8, 2014 [Page 8]
Internet-Draft Simple GSS July 2013
method.
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:
o callback function
o file descriptor or file handle into which a single byte (of any
value) will be written
o a condition variable (and associated mutex) on which a signal will
be sent
Other completion notification methods could be specified as well, but
these seem likely to be sufficient and reasonably portable.
2.6.1. C-Bindings
Williams Expires January 8, 2014 [Page 9]
Internet-Draft Simple GSS July 2013
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 */
2.7. GSS_Set_event_loop()
Inputs:
Williams Expires January 8, 2014 [Page 10]
Internet-Draft Simple GSS July 2013
context CONTEXT HANDLE Empty security context
event_loop_type INTEGER Type of event loop
event_loop UNSPECIFIED An event loop
event_loop_module UNSPECIFIED A module implementing the interface of
the given event loop type
Outputs:
o major_status INTEGER
o minor_status INTEGER
Return major status codes:
o GSS_S_COMPLETE indicates success.
o ...
o GSS_S_FAILURE indicates a general failure.
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.
The following event loop types are defined (but not their
interfaces):
o 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);
o EV_LIBVERTO <https://fedorahosted.org/libverto/>;
o EV_LIBEVENT <http://libevent.org/>
o EV_LIBEV <http://software.schmorp.de/pkg/libev.html>
o EV_GLIB <http://developer.gnome.org/glib/stable/>
o EV_TEVENT <http://tevent.samba.org/>
o EV_GCD <https://libdispatch.macosforge.org/>
Asynchronous security context stepping is OPTIONAL. It is
RECOMMENDED that mechanisms implement EV_LIBVERTO. Note that if the
Williams Expires January 8, 2014 [Page 11]
Internet-Draft Simple GSS July 2013
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.
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.
2.7.1. C-Bindings
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);
2.8. GSS_Indicate_event_loop_types()
Inputs:
input_cred_handle CREDENTIAL HANDLE May be GSS_C_NO_CREDENTIAL
Outputs:
o major_status INTEGER
o minor_status INTEGER
Williams Expires January 8, 2014 [Page 12]
Internet-Draft Simple GSS July 2013
o event_loop_types SET OF INTEGER
Return major status codes:
o GSS_S_COMPLETE indicates success.
o GSS_S_FAILURE indicates a general failure.
This function indicates what event loop types are supported the
mechanisms for the given credentials handle.
2.8.1. C-Bindings
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);
2.9. GSS_Set_context_role_init()
Inputs:
context CONTEXT HANDLE Empty security context handle
mech_type OID Mechanism OID
target_name NAME Name of target principal
Outputs:
o major_status INTEGER
o minor_status INTEGER
o event_loop_types SET OF INTEGER
Return major status codes:
o GSS_S_COMPLETE indicates success.
o ...
o GSS_S_FAILURE indicates a general failure.
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
Williams Expires January 8, 2014 [Page 13]
Internet-Draft Simple GSS July 2013
application calls this function and an acceptor does not; both call
GSS_Step_context() (see Section 2.8).
2.9.1. C-Bindings
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);
2.10. GSS_Step_context()
Inputs:
context CONTEXT HANDLE Empty security context
input_token OCTET STRING Input security context token, if any
Outputs:
o major_status INTEGER
o minor_status INTEGER
o output_token OCTET STRING -- output security context token, if any
o actual_mech OID -- OID of mechanism used
Return major status codes:
o GSS_S_COMPLETE indicates success.
o GSS_S_CONTINUE_NEEDED ...
o 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.
o All major status codes allowed for GSS_Init_sec_context() and
GSS_Accept_sec_context().
o GSS_S_FAILURE indicates a general failure.
This function steps through one step of security context token
exchange for the given security context.
Williams Expires January 8, 2014 [Page 14]
Internet-Draft Simple GSS July 2013
Acceptors call this without having called
GSS_Set_context_role_init(); see Section 2.9.
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.
2.10.1. C-Bindings
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);
Williams Expires January 8, 2014 [Page 15]
Internet-Draft Simple GSS July 2013
3. Security Considerations
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.
Williams Expires January 8, 2014 [Page 16]
Internet-Draft Simple GSS July 2013
4. IANA Considerations
[Add registrations for all the above functions.]
Williams Expires January 8, 2014 [Page 17]
Internet-Draft Simple GSS July 2013
5. References
5.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2743] Linn, J., "Generic Security Service Application Program
Interface Version 2, Update 1", RFC 2743, January 2000.
[RFC2744] Wray, J., "Generic Security Service API Version 2 :
C-bindings", RFC 2744, January 2000.
[RFC5056] Williams, N., "On the Use of Channel Bindings to Secure
Channels", RFC 5056, November 2007.
[RFC5587] Williams, N., "Extended Generic Security Service Mechanism
Inquiry APIs", RFC 5587, July 2009.
[I-D.williams-kitten-channel-bound-flag]
Williams, N., "Channel Binding Signalling for the Generic
Security Services Application Programming Interface",
draft-williams-kitten-channel-bound-flag-02 (work in
progress), February 2013.
5.2. Informative References
[RFC5653] Upadhyay, M. and S. Malkani, "Generic Security Service API
Version 2: Java Bindings Update", RFC 5653, August 2009.
Williams Expires January 8, 2014 [Page 18]
Internet-Draft Simple GSS July 2013
Author's Address
Nicolas Williams
Cryptonector, LLC
Email: nico@cryptonector.com
Williams Expires January 8, 2014 [Page 19]
