RFC 6339

RFC 6339: Context Token Encapsulate/Decapsulate and OID Comparison Functions for the Generic Security Service Application Program Interface (GSS-API) 🎀

Okay bestie, let's get into this one 💅 It's an IETF Standards Track doc, written by Simon Josefsson of SJD AB and Leif Hornquist Astrand of Apple, Inc., dated August 2011. Its ISSN is 2070-1721. The title block doesn't list anything it obsoletes or updates, so there's no drama there 🫶

Abstract

This document describes three abstract GSS-API interfaces that are used to encapsulate and decapsulate context tokens, and to compare OIDs. It also specifies C bindings for those abstract interfaces ✨

Status of This Memo

This is an Internet Standards Track document.

This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 5741.

Info about the current status of this doc, any errata, and how to send feedback can be found at http://www.rfc-editor.org/info/rfc6339 🌸

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 described in the Simplified BSD License 📜

Table of Contents

1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . . . 2
2.  Conventions Used in This Document . . . . . . . . . . . . . . . 2
3.  GSS_Encapsulate_token Call  . . . . . . . . . . . . . . . . . . 3
  3.1.  gss_encapsulate_token . . . . . . . . . . . . . . . . . . . 3
4.  GSS_Decapsulate_token Call  . . . . . . . . . . . . . . . . . . 4
  4.1.  gss_decapsulate_token . . . . . . . . . . . . . . . . . . . 5
5.  GSS_OID_equal Call  . . . . . . . . . . . . . . . . . . . . . . 6
  5.1.  gss_oid_equal . . . . . . . . . . . . . . . . . . . . . . . 6
6.  Test Vector . . . . . . . . . . . . . . . . . . . . . . . . . . 7
7.  Acknowledgements  . . . . . . . . . . . . . . . . . . . . . . . 7
8.  Security Considerations . . . . . . . . . . . . . . . . . . . . 7
9.  References  . . . . . . . . . . . . . . . . . . . . . . . . . . 7
  9.1.  Normative References  . . . . . . . . . . . . . . . . . . . 7
  9.2.  Informative Reference . . . . . . . . . . . . . . . . . . . 8

1. Introduction 🦋

GSS-API [RFC2743] is a framework that gives applications security services no matter which authentication mechanism they're using. 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, like Simple Authentication and Security Layer (SASL) GS2 [RFC5801], need to add and remove this token header. The header has some ASN.1 tags, a length, and the mechanism OID, and it lives on context tokens. This document adds two GSS-API interfaces, GSS_Encapsulate_token and GSS_Decapsulate_token, so GSS-API libraries can provide this functionality 💖

Comparing OIDs is useful, for example, when you want to check that a negotiated mechanism matches the one that was requested. This document adds one GSS-API interface, GSS_OID_equal, for that purpose 🌈

Text from this specification can be used as implementation documentation. That's why Sections 3, 4, 5, 6, and 8 should be considered code components 💅

2. Conventions Used in This Document ✨

This document uses terms from [RFC2743] and [RFC2744], and it's structured in a similar way to them. 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 one 🎀

3. GSS_Encapsulate_token Call 🌸

Inputs:

• input_token (OCTET STRING): buffer with token data to encapsulate
• token_oid (OBJECT IDENTIFIER): object identifier of the mechanism for the token

Outputs:

• major_status (INTEGER)
• output_token (OCTET STRING): encapsulated token data; the caller must release it with GSS_Release_buffer()

Return major_status codes:

• GSS_S_COMPLETE means completion was successful and the output parameters hold correct information.
• GSS_S_FAILURE means encapsulation failed for reasons not specified at the GSS-API level.

GSS_Encapsulate_token() is used to add the mechanism-independent token header to GSS-API context token data 🧚

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 values:       GSS status codes

GSS_S_COMPLETE         Indicates that completion was successful and
                       that output parameters hold correct
                       information.

GSS_S_FAILURE          Indicates that encapsulation failed for
                       reasons unspecified at the GSS-API level.

4. GSS_Decapsulate_token Call 🔥

Inputs:

• input_token (OCTET STRING): buffer with token to decapsulate
• token_oid (OBJECT IDENTIFIER): expected object identifier of token

Outputs:

• major_status (INTEGER)
• output_token (OCTET STRING): decapsulated token data; the caller must release it with GSS_Release_buffer()

Return major_status codes:

• GSS_S_COMPLETE means completion was successful and the output parameters hold correct information.
• GSS_S_DEFECTIVE_TOKEN means the token failed consistency checks (for example, an OID mismatch or ASN.1 DER length errors).
• GSS_S_FAILURE means decapsulation failed for reasons not specified at the GSS-API level.

GSS_Decapsulate_token() is used to remove the mechanism-independent token header from an initial GSS-API context token 👑

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 values:       GSS status codes

GSS_S_COMPLETE         Indicates that completion was successful and
                       that output parameters hold 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.

5. GSS_OID_equal Call 🌈

Inputs:

• first_oid (OBJECT IDENTIFIER): first object identifier to compare
• second_oid (OBJECT IDENTIFIER): second object identifier to compare

Return codes:

• non-0 when neither OID is GSS_C_NO_OID and the two OIDs are equal.
• 0 when the two OIDs are not identical, or when either OID is equal to GSS_C_NO_OID.

GSS_OID_equal() is used to compare two OIDs for equality. The value GSS_C_NO_OID will not match any OID, including GSS_C_NO_OID itself 🧚

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 values:       GSS status codes

non-0                  Neither OID is GSS_C_NO_OID, and the two OIDs
                       are equal.

0                      The two OIDs are not identical, or either OID
                       is equal to GSS_C_NO_OID.

---

🎀 that's part 1, bestie! Part 2 is coming up next with the test vector, the acknowledgements, the security considerations, and the references 🦋💖

Authors' Addresses ✨

Okay bestie, meet the two people behind this spec and where you can reach them 💌🎀

Simon Josefsson is the first author, and his contact details are below 🦋

Simon Josefsson
SJD AB
Hagagatan 24
Stockholm  113 47
SE

EMail: simon@josefsson.org
URI:   http://josefsson.org/

Love Hornquist Astrand is the second author, and her contact details are right here 🧚💜

Love Hornquist Astrand
Apple, Inc.

EMail: lha@apple.com