[Docs] [txt|pdf] [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 7, 2011                                     Apple, Inc.
                                                           April 5, 2011


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

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 October 7, 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 October 7, 2011          [Page 1]

Internet-Draft    GSS-API capsulate and OID comparison        April 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 October 7, 2011          [Page 2]

Internet-Draft    GSS-API capsulate and OID comparison        April 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 October 7, 2011          [Page 3]

Internet-Draft    GSS-API capsulate and OID comparison        April 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 October 7, 2011          [Page 4]

Internet-Draft    GSS-API capsulate and OID comparison        April 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 October 7, 2011          [Page 5]

Internet-Draft    GSS-API capsulate and OID comparison        April 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 October 7, 2011          [Page 6]

Internet-Draft    GSS-API capsulate and OID comparison        April 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 October 7, 2011          [Page 7]

Internet-Draft    GSS-API capsulate and OID comparison        April 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 October 7, 2011          [Page 8]

Internet-Draft    GSS-API capsulate and OID comparison        April 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 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 7, 2011          [Page 9]

Internet-Draft    GSS-API capsulate and OID comparison        April 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 otherwise
























Josefsson & Hornquist Astrand  Expires October 7, 2011         [Page 10]

Internet-Draft    GSS-API capsulate and OID comparison        April 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 October 7, 2011         [Page 11]

Internet-Draft    GSS-API capsulate and OID comparison        April 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.












































Josefsson & Hornquist Astrand  Expires October 7, 2011         [Page 12]

Internet-Draft    GSS-API capsulate and OID comparison        April 2011


8.  IANA Considerations

   None.
















































Josefsson & Hornquist Astrand  Expires October 7, 2011         [Page 13]

Internet-Draft    GSS-API capsulate and OID comparison        April 2011


9.  Security Considerations

   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 October 7, 2011         [Page 14]

Internet-Draft    GSS-API capsulate and OID comparison        April 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 October 7, 2011         [Page 15]

Internet-Draft    GSS-API capsulate and OID comparison        April 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 October 7, 2011         [Page 16]


Html markup produced by rfcmarkup 1.107, available from http://tools.ietf.org/tools/rfcmarkup/