Generic Security Service API Version 2 : C-bindings
obsoletes
- rfc-1509 — Generic Security Service API : C-bindings
updated by
- rfc-5896 — Generic Security Service Application Program Interface (GSS-API): Delegate if Approved by Policy
Extracted elements (31)
gss_export_name() requires a Mechanism Name (MN) input and produces a flat binary form suitable for direct byte comparison (e.g., memcmp). This design avoids the per-ACL-entry overhead of gss_import_name()/gss_compare_name() in large access-control list scenarios.
Inter-process context transfer (gss_export_sec_context/gss_import_sec_context) was introduced in GSS-API V2 to support the common server pattern of a parent that accepts security contexts and child processes that handle subsequent data exchange. Sharing a single context object between processes is impractical because it carries sequencing state, so export/import provides a clean ownership-transfer mechanism.
The default credential resolution algorithm (invoked via GSS_C_NO_CREDENTIAL) is designed to allow security contexts to be established using default behavior wherever possible, making applications more portable across mechanisms and platforms than those that explicitly call gss_acquire_cred().
The gss_name_t type is defined as a pointer to an implementation-defined (rather than void*) type so that C compilers can perform type-checking on behalf of the application programmer, reducing the likelihood of API misuse.
GSS_C_PROT_READY_FLAG was not defined in Version 1 of the GSS-API. Applications should not rely on implementations setting this flag in the final ret_flags; instead they should use per-message services after successful context establishment guided by GSS_C_INTEG_FLAG and GSS_C_CONF_FLAG.
The requirement to pair GSS_S_OLD_TOKEN and GSS_S_DUPLICATE_TOKEN with a routine error of GSS_S_FAILURE during context establishment did not exist in GSS-API version 1. Applications that must interoperate with v1 implementations must special-case these status codes.
Applications must treat gss_OID_desc values returned by GSS-API routines as read-only and must not attempt to deallocate them with free(). Storage for all OID sets returned to the application must be released with gss_release_oid_set().
Applications wishing to use per-message protection services on partially-established contexts (before GSS_S_COMPLETE) should check the GSS_C_PROT_READY_FLAG bit in ret_flags before invoking gss_wrap or gss_get_mic.
Delegation may only be provided at the explicit request of the application. If the application instructs gss_init_sec_context() that delegation is not desired, the implementation must not permit delegation to occur, overriding any mechanism-specific delegation controls.
During context establishment, GSS_S_OLD_TOKEN and GSS_S_DUPLICATE_TOKEN are fatal errors; GSS-API mechanisms must always return them paired with a routine error of GSS_S_FAILURE.
GSS-API implementations must impose a local access-control policy on callers of gss_acquire_cred() and gss_add_cred() to prevent unauthorized callers from acquiring credentials to which they are not entitled.
Portable applications must call gss_accept_sec_context() in a loop, using the token length field and return status (GSS_S_CONTINUE_NEEDED) to determine whether to send a token or wait for one, rather than assuming a fixed number of exchanges.
The minor_status parameter must always be set by a GSS-API routine, even when a calling error or generic fatal error is returned. Output parameters expected to return pointers to allocated storage must always be set (to NULL if no storage was allocated); associated length fields must be set to zero on error.
When a context supports optional services, mechanisms that may not provide a requested service must send at least one token from acceptor to initiator during context establishment so the initiating GSS-API can correctly report whether the service is available.
When a gss_buffer_desc describes a printable string, the length field must not count a trailing NUL character, and neither the GSS-API implementation nor the application should assume the presence of an uncounted trailing NUL.
Anonymous authentication allows a context initiator to authenticate a peer without revealing its own identity. The anonymous name returned by gss_accept_sec_context() must be syntactically distinguishable from any valid principal name and associated with GSS_C_NT_ANONYMOUS, since it may appear in audit logs.
GSS-API defines four call groups: credential management (gss_acquire_cred, gss_add_cred, gss_inquire_cred, gss_release_cred), context-level (gss_init_sec_context, gss_accept_sec_context, gss_delete_sec_context, gss_export_sec_context, gss_import_sec_context), per-message (gss_get_mic, gss_verify_mic, gss_wrap, gss_unwrap), and name manipulation (gss_import_name, gss_export_name, gss_compare_name, gss_canonicalize_name).
gss_buffer_desc consists of a size_t length field (total bytes, excluding any trailing NUL) and a void* value pointer. Storage returned to the application by GSS-API is allocated by the API and must be freed by the application with gss_release_buffer(); allocation of the gss_buffer_desc object itself is always the application's responsibility.
gss_cred_id_t is a caller-opaque credential handle implemented as a pointer or arithmetic type. A credential may contain at most one credential-element per supported mechanism; each element holds two credential-references—one for initiating and one for accepting contexts.
gss_name_t supports an internal opaque form that may hold multiple primitive names from different namespaces, and mechanism-specific contiguous octet-string forms. Names authenticated via gss_accept_sec_context() are always Mechanism Names (MNs) containing exactly one mechanism-specific primitive name.
gss_OID_set_desc contains a size_t count of OIDs and a gss_OID elements pointer to an array of gss_OID_desc objects. All OID sets returned by GSS-API are dynamically allocated (set descriptor, elements array, and each member OID) and must be fully released by the application with gss_release_oid_set().
Interprocess tokens are caller-opaque octet strings produced by gss_export_sec_context() in one process for consumption by gss_import_sec_context() in another. After a successful export the original context is made inaccessible and all context handles referring to it become invalid; gss_import_sec_context() creates a functionally identical replacement context.
OM_uint32 is the portable 32-bit unsigned integer type used throughout the C binding. Implementations should use the X/Open xom.h definition if available; otherwise the smallest natural unsigned type providing at least 32 bits of precision.
Optional context services are requested via req_flags to gss_init_sec_context(): delegation (GSS_C_DELEG_FLAG), mutual authentication (GSS_C_MUTUAL_FLAG), replay detection (GSS_C_REPLAY_FLAG), out-of-sequence detection (GSS_C_SEQUENCE_FLAG), anonymous authentication (GSS_C_ANON_FLAG), and confidentiality via gss_wrap (GSS_C_CONF_FLAG). Actual services provided are reported back in ret_flags.
Supplementary status bits in the lower 16 bits of a GSS major status include: GSS_S_CONTINUE_NEEDED (bit 0, returned by gss_init_sec_context or gss_accept_sec_context requiring another call), GSS_S_DUPLICATE_TOKEN (bit 1), GSS_S_OLD_TOKEN (bit 2), GSS_S_UNSEQ_TOKEN (bit 3), and GSS_S_GAP_TOKEN (bit 4).
The default credential behavior when GSS_C_NO_CREDENTIAL is passed follows a four-step fallback: (1) sole authorized principal, (2) platform default network identity, (3) mapped default local identity, (4) user-configurable default. The same four-step logic applies separately for gss_init_sec_context and gss_accept_sec_context.
Interprocess tokens generated by gss_export_sec_context() may contain sensitive data from the security context, including cryptographic keys. Applications must protect these tokens in transit and transfer them only to processes that are trustworthy.
Some mechanisms include actual channel binding data in context-establishment tokens rather than just a MIC. Applications should therefore not use confidential data as channel-binding components, since that data may be transmitted without encryption.
Channel bindings are structured as gss_channel_bindings_struct containing initiator_addrtype (OM_uint32), initiator_address (gss_buffer_desc), acceptor_addrtype (OM_uint32), acceptor_address (gss_buffer_desc), and application_data (gss_buffer_desc). The mechanism computes a MIC over the concatenation of these fields and binds it to the context-establishment token; mismatched bindings cause GSS_S_BAD_BINDINGS.
GSS major status codes are encoded in a 32-bit OM_uint32 value: bits 31–24 hold the calling error field, bits 23–16 hold the routine error field, and bits 15–0 hold the supplementary info field. A non-zero upper 16 bits indicates failure; GSS_S_xxx symbols equate to complete OM_uint32 values (e.g., GSS_S_BAD_NAMETYPE = 3<<16).
gss_OID_desc encodes an ASN.1 object identifier as a void* elements pointer to the BER-encoded value portion (tag and length octets excluded) and an OM_uint32 length giving the byte count. For example, the DASS mechanism OID has length 7 and seven octal-valued bytes.