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 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 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 #include #include 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 ; o EV_LIBEVENT o EV_LIBEV o EV_GLIB o EV_TEVENT o EV_GCD 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]