Network Working Group S. Josefsson Internet-Draft SJD AB Intended status: Standards Track L. Hornquist Astrand Expires: October 7, 2011 Apple, Inc. April 5, 2011 Context Token Encapsulate/Decapsulate and OID Comparison Functions for the Generic Security Service Application Program Interface (GSS-API) draft-josefsson-gss-capsulate-04 Abstract This document describes three abstract Generic Security Service Application Program Interface (GSS-API) interfaces used to encapsulate/decapsulate context tokens and compare OIDs. The document also specifies C bindings for the abstract interfaces. 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 October 7, 2011. Copyright Notice Copyright (c) 2011 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 Josefsson & Hornquist Astrand Expires October 7, 2011 [Page 1] Internet-Draft GSS-API capsulate and OID comparison April 2011 described in the Simplified BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Conventions used in this document . . . . . . . . . . . . . . 4 3. GSS_Encapsulate_token call . . . . . . . . . . . . . . . . . . 5 3.1. gss_encapsulate_token . . . . . . . . . . . . . . . . . . 6 4. GSS_Decapsulate_token call . . . . . . . . . . . . . . . . . . 7 4.1. gss_decapsulate_token . . . . . . . . . . . . . . . . . . 8 5. GSS_OID_equal call . . . . . . . . . . . . . . . . . . . . . . 9 5.1. gss_oid_equal . . . . . . . . . . . . . . . . . . . . . . 10 6. Test vector . . . . . . . . . . . . . . . . . . . . . . . . . 11 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 12 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 9. Security Considerations . . . . . . . . . . . . . . . . . . . 14 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 15 10.1. Normative References . . . . . . . . . . . . . . . . . . . 15 10.2. Informative References . . . . . . . . . . . . . . . . . . 15 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 16 Josefsson & Hornquist Astrand Expires October 7, 2011 [Page 2] Internet-Draft GSS-API capsulate and OID comparison April 2011 1. Introduction The Generic Security Service Application Program Interface (GSS-API) [RFC2743] is a framework that provides security services to applications using a variety of authentication mechanisms. There are widely implemented C bindings [RFC2744] for the abstract interface. For initial context tokens a mechanism-independent token format may be used, see section 3.1 of [RFC2743]. Some protocols, e.g., SASL GS2 [RFC5801], need the ability to add and remove this token header which contains some ASN.1 tags, a length and the mechanism OID to and from context tokens. This document adds two GSS-API interfaces (GSS_Encapsulate_token and GSS_Decapsulate_token) so that GSS-API libraries can provide this functionality. Being able to compare OIDs is useful, for example when validating that a negotiated mechanism matched the requested one. This document adds one GSS-API interface (GSS_OID_equal) for this purpose. The intention is that text from this specification should be possible to use for implementation documentation, and for this reason this entire document should be considered a code component. Josefsson & Hornquist Astrand Expires October 7, 2011 [Page 3] Internet-Draft GSS-API capsulate and OID comparison April 2011 2. Conventions used in this document The document uses terms from, and is structured in a similar way as, [RFC2743] and [RFC2744]. The normative reference to [RFC5587] is for the C types "gss_const_buffer_t" and "gss_const_OID", nothing else from that document is required to implement this document. Josefsson & Hornquist Astrand Expires October 7, 2011 [Page 4] Internet-Draft GSS-API capsulate and OID comparison April 2011 3. GSS_Encapsulate_token call Inputs: o input_token OCTET STRING -- buffer with token data to encapsulate o token_oid OBJECT IDENTIFIER -- object identifier of mechanism for the token Outputs: o major_status INTEGER o output_token OCTET STRING -- Encapsulated token data; caller must release with GSS_Release_buffer() Return major_status codes: o GSS_S_COMPLETE indicates successful completion, and that output parameters holds correct information. o GSS_S_FAILURE indicates that encapsulation failed for reasons unspecified at the GSS-API level. GSS_Encapsulate_token() is used to add the mechanism-independent token header to GSS-API context token data. Josefsson & Hornquist Astrand Expires October 7, 2011 [Page 5] Internet-Draft GSS-API capsulate and OID comparison April 2011 3.1. gss_encapsulate_token OM_uint32 gss_encapsulate_token ( gss_const_buffer_t input_token, gss_const_OID token_oid, gss_buffer_t output_token) Purpose: Add the mechanism-independent token header to GSS-API context token data. Parameters: input_token buffer, opaque, read Buffer with GSS-API context token data. token_oid Object ID, read Object identifier of token. output_token buffer, opaque, modify Encapsulated token data; caller must release with gss_release_buffer(). Function value: GSS status code GSS_S_COMPLETE Indicates successful completion, and that output parameters holds correct information. GSS_S_FAILURE Indicates that encapsulation failed for reasons unspecified at the GSS-API level. Josefsson & Hornquist Astrand Expires October 7, 2011 [Page 6] Internet-Draft GSS-API capsulate and OID comparison April 2011 4. GSS_Decapsulate_token call Inputs: o input_token OCTET STRING -- buffer with token to decapsulate o token_oid OBJECT IDENTIFIER -- expected object identifier of token Outputs: o major_status INTEGER o output_token OCTET STRING -- Decapsulated token data; caller must release with GSS_Release_buffer() Return major_status codes: o GSS_S_COMPLETE indicates successful completion, and that output parameters holds correct information. o GSS_S_DEFECTIVE_TOKEN means that the token failed consistency checks (e.g., OID mismatch or ASN.1 DER length errors). o GSS_S_FAILURE indicates that decapsulation failed for reasons unspecified at the GSS-API level. GSS_Decapsulate_token() is used to remove the mechanism- independent token header from an initial GSS-API context token. Josefsson & Hornquist Astrand Expires October 7, 2011 [Page 7] Internet-Draft GSS-API capsulate and OID comparison April 2011 4.1. gss_decapsulate_token OM_uint32 gss_decapsulate_token ( gss_const_buffer_t input_token, gss_const_OID token_oid, gss_buffer_t output_token) Purpose: Remove the mechanism-independent token header from an initial GSS-API context token. Parameters: input_token buffer, opaque, read Buffer with GSS-API context token. token_oid Object ID, read Expected object identifier of token. output_token buffer, opaque, modify Decapsulated token data; caller must release with gss_release_buffer(). Function value: GSS status code GSS_S_COMPLETE Indicates successful completion, and that output parameters holds correct information. GSS_S_DEFECTIVE_TOKEN Means that the token failed consistency checks (e.g., OID mismatch or ASN.1 DER length errors). GSS_S_FAILURE Indicates that decapsulation failed for reasons unspecified at the GSS-API level. Josefsson & Hornquist Astrand Expires October 7, 2011 [Page 8] Internet-Draft GSS-API capsulate and OID comparison April 2011 5. GSS_OID_equal call Inputs: o first_oid OBJECT IDENTIFIER -- first object identifier to compare o second_oid OBJECT IDENTIFIER -- second object identifier to compare Return codes: o non-0 when neither OID is GSS_C_NO_OID and the two OIDs are equal o 0 otherwise GSS_OID_equal() is used to add compare two OIDs for equality. The value GSS_C_NO_OID will not match any OID, including GSS_C_NO_OID itself. Josefsson & Hornquist Astrand Expires October 7, 2011 [Page 9] Internet-Draft GSS-API capsulate and OID comparison April 2011 5.1. gss_oid_equal extern int gss_oid_equal ( gss_const_OID first_oid, gss_const_OID second_oid ) Purpose: Compare two OIDs for equality. The value GSS_C_NO_OID will not match any OID, including GSS_C_NO_OID itself. Parameters: first_oid Object ID, read First object identifier to compare. second_oid Object ID, read Second object identifier to compare. Function value: GSS status code non-0 neither OID is GSS_C_NO_OID and the two OIDs are equal 0 otherwise Josefsson & Hornquist Astrand Expires October 7, 2011 [Page 10] Internet-Draft GSS-API capsulate and OID comparison April 2011 6. Test vector For the GSS_Encapsulate_token function, if the "input_token" buffer is the 3 bytes octet sequence "foo" and the "token_oid" OID is 1.2.840.113554.1.2.2, which encoded corresponds to the 9 bytes long octet sequence (using C notation) "\x2a\x86\x48\x86\xf7\x12\x01\x02\x02", the output should be the 16 byte long octet sequence (again in C notation) "\x60\x0e\x06\x09\x2a\x86\x48\x86\xf7\x12\x01\x02\x02\x66\x6f\x6f". These values may be used to also test the GSS_Decapsulate_token interface. Josefsson & Hornquist Astrand Expires October 7, 2011 [Page 11] Internet-Draft GSS-API capsulate and OID comparison April 2011 7. Acknowledgements Greg Hudson pointed out the 'const' problem with the C bindings in earlier versions of this document, and Luke Howard suggested to resolve it by using the RFC 5587 types. Stephen Farrell suggested several editorial improvements and the security consideration regarding absent security features of the encapsulation function. Josefsson & Hornquist Astrand Expires October 7, 2011 [Page 12] Internet-Draft GSS-API capsulate and OID comparison April 2011 8. IANA Considerations None. Josefsson & Hornquist Astrand Expires October 7, 2011 [Page 13] Internet-Draft GSS-API capsulate and OID comparison April 2011 9. Security Considerations Encapsulation of data does not provide any kind of integrity or confidentiality. Implementations needs to treat input as potentially untrustworthy for purposes of dereferencing memory objects to avoid security vulnerabilities. In particular, ASN.1 DER length fields is a common source of mistakes. Josefsson & Hornquist Astrand Expires October 7, 2011 [Page 14] Internet-Draft GSS-API capsulate and OID comparison April 2011 10. References 10.1. Normative References [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. [RFC5587] Williams, N., "Extended Generic Security Service Mechanism Inquiry APIs", RFC 5587, July 2009. 10.2. Informative References [RFC5801] Josefsson, S. and N. Williams, "Using Generic Security Service Application Program Interface (GSS-API) Mechanisms in Simple Authentication and Security Layer (SASL): The GS2 Mechanism Family", RFC 5801, July 2010. Josefsson & Hornquist Astrand Expires October 7, 2011 [Page 15] Internet-Draft GSS-API capsulate and OID comparison April 2011 Authors' Addresses Simon Josefsson SJD AB Hagagatan 24 Stockholm 113 47 SE Email: simon@josefsson.org URI: http://josefsson.org/ Love Hornquist Astrand Apple, Inc. Email: lha@apple.com Josefsson & Hornquist Astrand Expires October 7, 2011 [Page 16]