Context Token Encapsulate/Decapsulate and OID Comparison Functions for the Generic Security Service Application Program Interface (GSS-API)
draft-josefsson-gss-capsulate-05
The information below is for an old version of the document that is already published as an RFC.
| Document | Type |
This is an older version of an Internet-Draft that was ultimately published as RFC 6339.
|
|
|---|---|---|---|
| Authors | Simon Josefsson , Love Astrand | ||
| Last updated | 2015-10-14 (Latest revision 2011-05-17) | ||
| RFC stream | Internet Engineering Task Force (IETF) | ||
| Intended RFC status | Proposed Standard | ||
| Formats | |||
| Reviews | |||
| Stream | WG state | (None) | |
| Document shepherd | (None) | ||
| IESG | IESG state | Became RFC 6339 (Proposed Standard) | |
| Action Holders |
(None)
|
||
| Consensus boilerplate | Unknown | ||
| Telechat date | (None) | ||
| Responsible AD | Stephen Farrell | ||
| IESG note | |||
| Send notices to | alexey.melnikov@isode.com |
draft-josefsson-gss-capsulate-05
Network Working Group S. Josefsson
Internet-Draft SJD AB
Intended status: Standards Track L. Hornquist Astrand
Expires: November 19, 2011 Apple, Inc.
May 18, 2011
Context Token Encapsulate/Decapsulate and OID Comparison Functions for
the Generic Security Service Application Program Interface (GSS-API)
draft-josefsson-gss-capsulate-05
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 November 19, 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 November 19, 2011 [Page 1]
Internet-Draft GSS-API capsulate and OID comparison May 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 November 19, 2011 [Page 2]
Internet-Draft GSS-API capsulate and OID comparison May 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 November 19, 2011 [Page 3]
Internet-Draft GSS-API capsulate and OID comparison May 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 November 19, 2011 [Page 4]
Internet-Draft GSS-API capsulate and OID comparison May 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 November 19, 2011 [Page 5]
Internet-Draft GSS-API capsulate and OID comparison May 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 November 19, 2011 [Page 6]
Internet-Draft GSS-API capsulate and OID comparison May 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 November 19, 2011 [Page 7]
Internet-Draft GSS-API capsulate and OID comparison May 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 November 19, 2011 [Page 8]
Internet-Draft GSS-API capsulate and OID comparison May 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.
Josefsson & Hornquist Astrand Expires November 19, 2011 [Page 9]
Internet-Draft GSS-API capsulate and OID comparison May 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 When the two OIDs are not identical or
either OID is equal to GSS_C_NO_OID.
Josefsson & Hornquist Astrand Expires November 19, 2011 [Page 10]
Internet-Draft GSS-API capsulate and OID comparison May 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 November 19, 2011 [Page 11]
Internet-Draft GSS-API capsulate and OID comparison May 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.
Chris Lonvick suggested some improvements.
Josefsson & Hornquist Astrand Expires November 19, 2011 [Page 12]
Internet-Draft GSS-API capsulate and OID comparison May 2011
8. IANA Considerations
None.
Josefsson & Hornquist Astrand Expires November 19, 2011 [Page 13]
Internet-Draft GSS-API capsulate and OID comparison May 2011
9. 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 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 November 19, 2011 [Page 14]
Internet-Draft GSS-API capsulate and OID comparison May 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 November 19, 2011 [Page 15]
Internet-Draft GSS-API capsulate and OID comparison May 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 November 19, 2011 [Page 16]