[Docs] [txt|pdf|xml|html] [Tracker] [Email] [Diff1] [Diff2] [Nits]

Versions: 00 01 02 03 04 05 RFC 6339

Network Working Group                                       S. Josefsson
Internet-Draft                                                    SJD AB
Intended status: Standards Track                    L. Hornquist Astrand
Expires: October 2, 2010                                     Apple, 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



Josefsson & Hornquist Astrand  Expires October 2, 2010          [Page 1]

Internet-Draft    GSS-API capsulate and OID comparison        March 2010


   (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 . . . . . . . . . . . . . . . . . . . . . . . . .  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.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 11
   7.  Security Considerations  . . . . . . . . . . . . . . . . . . . 12
   8.  References . . . . . . . . . . . . . . . . . . . . . . . . . . 13
     8.1.  Normative References . . . . . . . . . . . . . . . . . . . 13
     8.2.  Informative References . . . . . . . . . . . . . . . . . . 13
   Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 14


























Josefsson & Hornquist Astrand  Expires October 2, 2010          [Page 2]

Internet-Draft    GSS-API capsulate and OID comparison        March 2010


1.  Introduction

   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 [I-D.ietf-sasl-gs2], 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.






























Josefsson & Hornquist Astrand  Expires October 2, 2010          [Page 3]

Internet-Draft    GSS-API capsulate and OID comparison        March 2010


2.  Conventions used in this document

   The document uses terms from, and is structured in a similar way as,
   [RFC2743] and [RFC2744].















































Josefsson & Hornquist Astrand  Expires October 2, 2010          [Page 4]

Internet-Draft    GSS-API capsulate and OID comparison        March 2010


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 October 2, 2010          [Page 5]

Internet-Draft    GSS-API capsulate and OID comparison        March 2010


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.



















Josefsson & Hornquist Astrand  Expires October 2, 2010          [Page 6]

Internet-Draft    GSS-API capsulate and OID comparison        March 2010


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 October 2, 2010          [Page 7]

Internet-Draft    GSS-API capsulate and OID comparison        March 2010


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.














Josefsson & Hornquist Astrand  Expires October 2, 2010          [Page 8]

Internet-Draft    GSS-API capsulate and OID comparison        March 2010


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.































Josefsson & Hornquist Astrand  Expires October 2, 2010          [Page 9]

Internet-Draft    GSS-API capsulate and OID comparison        March 2010


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
























Josefsson & Hornquist Astrand  Expires October 2, 2010         [Page 10]

Internet-Draft    GSS-API capsulate and OID comparison        March 2010


6.  IANA Considerations

   None.
















































Josefsson & Hornquist Astrand  Expires October 2, 2010         [Page 11]

Internet-Draft    GSS-API capsulate and OID comparison        March 2010


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.













































Josefsson & Hornquist Astrand  Expires October 2, 2010         [Page 12]

Internet-Draft    GSS-API capsulate and OID comparison        March 2010


8.  References

8.1.  Normative References

   [RFC2743]  Linn, J., "Generic Security Service Application Program
              Interface Version 2, Update 1", RFC 2743, January 2000.

8.2.  Informative References

   [RFC2744]  Wray, J., "Generic Security Service API Version 2 :
              C-bindings", RFC 2744, January 2000.

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



































Josefsson & Hornquist Astrand  Expires October 2, 2010         [Page 13]

Internet-Draft    GSS-API capsulate and OID comparison        March 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  Expires October 2, 2010         [Page 14]


Html markup produced by rfcmarkup 1.109, available from https://tools.ietf.org/tools/rfcmarkup/