One document matched: draft-josefsson-gss-capsulate-00.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 GS2 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-sasl-gs2.xml'>
	  ]>

<?rfc compact="no"?>
<?rfc toc="yes"?>
<?rfc symrefs="yes"?>

<rfc category="std" ipr="trust200902"
     docName="draft-josefsson-gss-capsulate-00">

  <front>

    <title abbrev="GSS-API en/de-capsulate">
      Context Token Encapsulate/Decapsulate 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="March" year="2010"/>

    <abstract>

      <t>This document describes two abstract Generic Security Service
	Application Program Interface (GSS-API) interfaces used to
	encapsulate and decapsulate context tokens, and their C
	bindings.</t>

    </abstract>
    
  </front>

    <middle>

	<section anchor="intro"
		 title="Introduction">

	  <t>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="RFC2743"/> 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="I-D.ietf-sasl-gs2"/>, needs the ability to
	    add and remove the token header from context tokens.  This
	    document adds GSS-API interfaces so that GSS-API libraries
	    can provide this functionality.</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"/>.</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 (
    const gss_buffer_t input_token,
    const gss_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 (
    const gss_buffer_t input_token,
    const gss_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="iana"
		 title="IANA Considerations">

	  <t>None.</t>

	</section>

	<section anchor="security"
		 title="Security Considerations">

	    <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;

	</references>

	<references title="Informative References">

	  &RFC2744;
	  &GS2;

	</references>

    </back>

</rfc>