Network Working Group N. Williams
Internet-Draft Cryptonector
Updates: 2743, 2744 (if approved) July 07, 2013
Intended status: Standards Track
Expires: January 08, 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 08, 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 described in the Simplified BSD License.

Table of Contents

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

2. Simplified API

We add a function for creating “empty” security contexts:

We add the following new mutator functions for empty security contexts:

We add a function for stepping through security context token exchanges:

We add a function for retrieving delegated credentials from a security context token:

2.1. GSS_Create_sec_context()

Inputs:

Outputs:

Return major status codes:

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:

Return major status codes:

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.

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:

Return major status codes:

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

Return major status codes:

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:

Return major status codes:

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:

Return major status codes:

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.

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:

Other completion notification methods could be specified as well, but these seem likely to be sufficient and reasonably portable.

2.6.1. C-Bindings

 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:

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:

Return major status codes:

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

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.

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:

Return major status codes:

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:

Return major status codes:

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

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:

Return major status codes:

This function steps through one step of security context token exchange for the given security context.

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

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.

4. IANA Considerations

[Add registrations for all the above functions.]

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", Internet-Draft draft-williams-kitten-channel-bound-flag-02, 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.

Author's Address

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