One document matched: draft-josefsson-gss-capsulate-05.xml
<?xml version="1.0"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY RFC2743 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2743.xml'>
<!ENTITY RFC2744 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2744.xml'>
<!ENTITY RFC5587 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5587.xml'>
<!ENTITY RFC5801 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5801.xml'>
]>
<?rfc compact="no"?>
<?rfc toc="yes"?>
<?rfc symrefs="yes"?>
<rfc category="std" ipr="trust200902"
docName="draft-josefsson-gss-capsulate-05">
<front>
<title abbrev="GSS-API capsulate and OID comparison">
Context Token Encapsulate/Decapsulate and OID Comparison
Functions for the Generic Security Service Application Program
Interface (GSS-API)
</title>
<author initials="S." surname="Josefsson"
fullname="Simon Josefsson">
<organization>SJD AB</organization>
<address>
<postal>
<street>Hagagatan 24</street>
<city>Stockholm</city>
<code>113 47</code>
<country>SE</country>
</postal>
<email>simon@josefsson.org</email>
<uri>http://josefsson.org/</uri>
</address>
</author>
<author initials='L.' surname="Hornquist Astrand"
fullname='Love Hornquist Astrand'>
<organization>Apple, Inc.</organization>
<address>
<email>lha@apple.com</email>
</address>
</author>
<date month="May" year="2011"/>
<abstract>
<t>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.</t>
</abstract>
</front>
<middle>
<section anchor="intro"
title="Introduction">
<t>The Generic Security Service Application Program Interface
(GSS-API) <xref target="RFC2743"/> is a framework that provides
security services to applications using a variety of
authentication mechanisms. There are widely implemented C
bindings <xref target="RFC2744"/> for the abstract
interface.</t>
<t>For initial context tokens a mechanism-independent token
format may be used, see section 3.1 of <xref target="RFC2743"/>.
Some protocols, e.g., SASL GS2 <xref target="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.</t>
<t>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.</t>
<t>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.</t>
</section>
<section title="Conventions used in this document">
<t>The document uses terms from, and is structured in a similar
way as, <xref target="RFC2743"/> and <xref target="RFC2744"/>.
The normative reference to <xref target="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.</t>
</section>
<section anchor="GSS_Encapsulate_token"
title="GSS_Encapsulate_token call">
<figure>
<artwork>
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.
</artwork>
</figure>
<t><vspace blankLines="10000" /></t>
<section anchor="gss_encapsulate_token"
title="gss_encapsulate_token">
<figure>
<artwork>
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.
</artwork>
</figure>
</section>
</section>
<section anchor="GSS_Decapsulate_token"
title="GSS_Decapsulate_token call">
<figure>
<artwork>
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.
</artwork>
</figure>
<t><vspace blankLines="10000" /></t>
<section anchor="gss_decapsulate_token"
title="gss_decapsulate_token">
<figure>
<artwork>
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.
</artwork>
</figure>
</section>
</section>
<section anchor="GSS_OID_equal"
title="GSS_OID_equal call">
<figure>
<artwork>
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.
</artwork>
</figure>
<t><vspace blankLines="10000" /></t>
<section anchor="gss_oid_equal"
title="gss_oid_equal">
<figure>
<artwork>
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.
</artwork>
</figure>
</section>
</section>
<section anchor="test-vector"
title="Test vector">
<t>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.</t>
</section>
<section anchor="ack"
title="Acknowledgements">
<t>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.</t>
</section>
<section anchor="iana"
title="IANA Considerations">
<t>None.</t>
</section>
<section anchor="security"
title="Security Considerations">
<t>The security considerations of the base GSS-API specification
(<xref target="RFC2743"/>) and the base C bindings (<xref
target="RFC2744"/>) are inherited.</t>
<t>Encapsulation of data does not provide any kind of integrity
or confidentiality.</t>
<t>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.</t>
</section>
</middle>
<back>
<references title="Normative References">
&RFC2743;
&RFC2744;
&RFC5587;
</references>
<references title="Informative References">
&RFC5801;
</references>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-21 17:44:33 |