TOC 
Network Working GroupS. Josefsson
Internet-DraftSJD AB
Intended status: Standards TrackL. Hornquist Astrand
Expires: October 2, 2010Apple, Inc.
 March 31, 2010


Context Token Encapsulate/Decapsulate and OID Comparison Functions for the Generic Security Service Application Program Interface (GSS-API)
draft-josefsson-gss-capsulate-01

Abstract

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

Status of this Memo

This Internet-Draft is submitted to IETF in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts.

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.”

The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt.

The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html.

This Internet-Draft will expire on October 2, 2010.

Copyright Notice

Copyright (c) 2010 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 BSD License.



Table of Contents

1.  Introduction
2.  Conventions used in this document
3.  GSS_Encapsulate_token call
    3.1.  gss_encapsulate_token
4.  GSS_Decapsulate_token call
    4.1.  gss_decapsulate_token
5.  GSS_OID_equal call
    5.1.  gss_oid_equal
6.  IANA Considerations
7.  Security Considerations
8.  References
    8.1.  Normative References
    8.2.  Informative References
§  Authors' Addresses




 TOC 

1.  Introduction

Generic Security Service Application Program Interface (GSS-API) [RFC2743] (Linn, J., “Generic Security Service Application Program Interface Version 2, Update 1,” January 2000.) is a framework that provides security services to applications using a variety of authentication mechanisms. There are widely implemented C bindings [RFC2744] (Wray, J., “Generic Security Service API Version 2 : C-bindings,” January 2000.) for the abstract interface.

For initial context tokens a mechanism-independent token format may be used, see section 3.1 of [RFC2743] (Linn, J., “Generic Security Service Application Program Interface Version 2, Update 1,” January 2000.). Some protocols, e.g., SASL GS2 [I‑D.ietf‑sasl‑gs2] (Josefsson, S. and N. Williams, “Using GSS-API Mechanisms in SASL: The GS2 Mechanism Family,” January 2010.), needs the ability to add and remove the token header 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 an 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.



 TOC 

2.  Conventions used in this document

The document uses terms from, and is structured in a similar way as, [RFC2743] (Linn, J., “Generic Security Service Application Program Interface Version 2, Update 1,” January 2000.) and [RFC2744] (Wray, J., “Generic Security Service API Version 2 : C-bindings,” January 2000.).



 TOC 

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.



 TOC 

3.1.  gss_encapsulate_token

  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.


 TOC 

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.



 TOC 

4.1.  gss_decapsulate_token

  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.


 TOC 

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.



 TOC 

5.1.  gss_oid_equal

  extern int
  gss_oid_equal (
    const gss_OID first_oid,
    const gss_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


 TOC 

6.  IANA Considerations

None.



 TOC 

7.  Security Considerations

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.



 TOC 

8.  References



 TOC 

8.1. Normative References

[RFC2743] Linn, J., “Generic Security Service Application Program Interface Version 2, Update 1,” RFC 2743, January 2000 (TXT).


 TOC 

8.2. Informative References

[RFC2744] Wray, J., “Generic Security Service API Version 2 : C-bindings,” RFC 2744, January 2000 (TXT).
[I-D.ietf-sasl-gs2] Josefsson, S. and N. Williams, “Using GSS-API Mechanisms in SASL: The GS2 Mechanism Family,” draft-ietf-sasl-gs2-20 (work in progress), January 2010 (TXT).


 TOC 

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