Context Token Encapsulate/Decapsulate and OID Comparison Functions for the Generic Security Service Application Program Interface (GSS-API)
Extracted elements (15)
The C bindings use the types gss_const_buffer_t and gss_const_OID from RFC 5587 to address a 'const' problem present in earlier versions of the specification, ensuring const-correctness for read-only parameters without requiring anything else from RFC 5587.
These three interfaces were added because protocols such as SASL GS2 (RFC 5801) need to programmatically add and remove the mechanism-independent GSS-API token header (ASN.1 tags, length, OID), and OID comparison is needed to validate that a negotiated mechanism matches the requested one. Prior to this document, GSS-API libraries lacked standard APIs for these operations.
GSS_C_NO_OID passed to GSS_OID_equal() will not match any OID, including another GSS_C_NO_OID. Callers must not rely on GSS_C_NO_OID equality behavior when validating negotiated mechanisms.
GSS_Decapsulate_token() returns GSS_S_DEFECTIVE_TOKEN when the encapsulated token fails consistency checks such as an OID mismatch between the token header and the expected token_oid, or ASN.1 DER length field errors, distinguishing these from generic failures.
The caller of gss_encapsulate_token() and gss_decapsulate_token() MUST release the output_token buffer with gss_release_buffer() after use.
GSS_Decapsulate_token() removes the mechanism-independent token header from an initial GSS-API context token, validating the OID and ASN.1 DER structure. Returns GSS_S_COMPLETE, GSS_S_DEFECTIVE_TOKEN (OID mismatch or ASN.1 DER length errors), or GSS_S_FAILURE.
GSS_Encapsulate_token() adds the mechanism-independent token header (ASN.1 tags, length, and mechanism OID) to GSS-API context token data, returning the encapsulated token or GSS_S_FAILURE on error. The caller must release the output buffer with GSS_Release_buffer().
GSS_OID_equal() compares two OIDs for equality, returning non-zero when neither OID is GSS_C_NO_OID and the two OIDs are equal, and zero otherwise. GSS_C_NO_OID does not match any OID, including itself.
The C binding gss_decapsulate_token() takes a gss_const_buffer_t input_token and gss_const_OID token_oid (the expected OID), and writes the decapsulated data into a gss_buffer_t output_token. Returns OM_uint32 status codes including GSS_S_DEFECTIVE_TOKEN when consistency checks fail.
The C binding gss_encapsulate_token() takes a gss_const_buffer_t input_token and gss_const_OID token_oid, and writes the encapsulated result into a gss_buffer_t output_token. Returns OM_uint32 status codes GSS_S_COMPLETE or GSS_S_FAILURE.
The C binding gss_oid_equal() takes two gss_const_OID parameters and returns a C int: non-zero if both OIDs are non-null and equal, zero if they differ or either is GSS_C_NO_OID.
Encapsulation of data using GSS_Encapsulate_token does not provide any kind of integrity or confidentiality protection; the wrapper only identifies the mechanism via OID.
Implementations must treat input tokens as potentially untrustworthy when dereferencing memory objects to avoid security vulnerabilities. ASN.1 DER length fields are specifically called out as a common source of mistakes.
The security considerations of the base GSS-API specification (RFC 2743) and the base C bindings (RFC 2744) are inherited by this document.
The encapsulated token format is an ASN.1 DER SEQUENCE: a 0x60 application tag byte, a DER-encoded length, a 0x06 OID tag byte, the DER-encoded OID length, the OID octets, then the raw token data. For example, 3-byte input 'foo' with OID 1.2.840.113554.1.2.2 produces the 16-byte sequence 60 0e 06 09 2a 86 48 86 f7 12 01 02 02 66 6f 6f.