summaryrefslogtreecommitdiff
path: root/doc/rfc/rfc6339.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/rfc/rfc6339.txt')
-rw-r--r--doc/rfc/rfc6339.txt451
1 files changed, 451 insertions, 0 deletions
diff --git a/doc/rfc/rfc6339.txt b/doc/rfc/rfc6339.txt
new file mode 100644
index 0000000..0c0301d
--- /dev/null
+++ b/doc/rfc/rfc6339.txt
@@ -0,0 +1,451 @@
+
+
+
+
+
+
+Internet Engineering Task Force (IETF) S. Josefsson
+Request for Comments: 6339 SJD AB
+Category: Standards Track L. Hornquist Astrand
+ISSN: 2070-1721 Apple, Inc.
+ August 2011
+
+
+ Context Token Encapsulate/Decapsulate and OID Comparison Functions for
+ the Generic Security Service Application Program Interface (GSS-API)
+
+Abstract
+
+ This document describes three abstract Generic Security Service
+ Application Program Interface (GSS-API) interfaces used to
+ encapsulate/decapsulate context tokens and compare OIDs. This
+ document also specifies C bindings for the abstract interfaces.
+
+Status of This Memo
+
+ This is an Internet Standards Track document.
+
+ This document is a product of the Internet Engineering Task Force
+ (IETF). It represents the consensus of the IETF community. It has
+ received public review and has been approved for publication by the
+ Internet Engineering Steering Group (IESG). Further information on
+ Internet Standards is available in Section 2 of RFC 5741.
+
+ Information about the current status of this document, any errata,
+ and how to provide feedback on it may be obtained at
+ http://www.rfc-editor.org/info/rfc6339.
+
+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
+ described in the Simplified BSD License.
+
+
+
+
+
+
+Josefsson & Hornquist Astrand Standards Track [Page 1]
+
+RFC 6339 GSS-API Capsulate and OID Comparison August 2011
+
+
+Table of Contents
+
+ 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2
+ 2. Conventions Used in This Document . . . . . . . . . . . . . . . 2
+ 3. GSS_Encapsulate_token Call . . . . . . . . . . . . . . . . . . 3
+ 3.1. gss_encapsulate_token . . . . . . . . . . . . . . . . . . . 3
+ 4. GSS_Decapsulate_token Call . . . . . . . . . . . . . . . . . . 4
+ 4.1. gss_decapsulate_token . . . . . . . . . . . . . . . . . . . 5
+ 5. GSS_OID_equal Call . . . . . . . . . . . . . . . . . . . . . . 6
+ 5.1. gss_oid_equal . . . . . . . . . . . . . . . . . . . . . . . 6
+ 6. Test Vector . . . . . . . . . . . . . . . . . . . . . . . . . . 7
+ 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 7
+ 8. Security Considerations . . . . . . . . . . . . . . . . . . . . 7
+ 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 7
+ 9.1. Normative References . . . . . . . . . . . . . . . . . . . 7
+ 9.2. Informative Reference . . . . . . . . . . . . . . . . . . . 8
+
+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., Simple
+ Authentication and Security Layer (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 matches the requested one. This document
+ adds one GSS-API interface (GSS_OID_equal) for this purpose.
+
+ Text from this specification can be used as implementation
+ documentation, and for this reason, Sections 3, 4, 5, 6, and 8 should
+ be considered code components.
+
+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 Standards Track [Page 2]
+
+RFC 6339 GSS-API Capsulate and OID Comparison August 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 that completion was successful and that
+ output parameters hold 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.
+
+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.
+
+
+
+
+
+Josefsson & Hornquist Astrand Standards Track [Page 3]
+
+RFC 6339 GSS-API Capsulate and OID Comparison August 2011
+
+
+ output_token buffer, opaque, modify
+ Encapsulated token data; caller must release
+ with gss_release_buffer().
+
+ Function values: GSS status codes
+
+ GSS_S_COMPLETE Indicates that completion was successful and
+ that output parameters hold correct
+ information.
+
+ GSS_S_FAILURE Indicates that encapsulation failed for
+ reasons unspecified at the GSS-API level.
+
+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 that completion was successful and that
+ output parameters hold 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 Standards Track [Page 4]
+
+RFC 6339 GSS-API Capsulate and OID Comparison August 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 values: GSS status codes
+
+ GSS_S_COMPLETE Indicates that completion was successful and
+ that output parameters hold 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 Standards Track [Page 5]
+
+RFC 6339 GSS-API Capsulate and OID Comparison August 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 when the two OIDs are not identical or either OID is equal to
+ GSS_C_NO_OID.
+
+ 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.
+
+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 values: GSS status codes
+
+ non-0 Neither OID is GSS_C_NO_OID, and the two OIDs
+ are equal.
+
+ 0 The two OIDs are not identical, or either OID
+ is equal to GSS_C_NO_OID.
+
+
+
+Josefsson & Hornquist Astrand Standards Track [Page 6]
+
+RFC 6339 GSS-API Capsulate and OID Comparison August 2011
+
+
+6. Test Vector
+
+ For the GSS_Encapsulate_token function, if the "input_token" buffer
+ is the 3-byte octet sequence "foo" and the "token_oid" OID is
+ 1.2.840.113554.1.2.2, which encoded corresponds to the 9-byte-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 also be used to test the GSS_Decapsulate_token
+ interface.
+
+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 [RFC5587] types. Stephen Farrell suggested
+ several editorial improvements and the security consideration
+ regarding absent security features of the encapsulation function.
+ Chris Lonvick suggested some improvements.
+
+8. Security Considerations
+
+ The security considerations of the base GSS-API specification
+ ([RFC2743]) and the base C bindings ([RFC2744]) are inherited.
+
+ Encapsulation of data does not provide any kind of integrity or
+ confidentiality.
+
+ Implementations need to treat input as potentially untrustworthy for
+ purposes of dereferencing memory objects to avoid security
+ vulnerabilities. In particular, ASN.1 DER length fields are a common
+ source of mistakes.
+
+9. References
+
+9.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.
+
+
+
+
+
+Josefsson & Hornquist Astrand Standards Track [Page 7]
+
+RFC 6339 GSS-API Capsulate and OID Comparison August 2011
+
+
+9.2. Informative Reference
+
+ [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.
+
+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 Standards Track [Page 8]
+