Generic Security Service Application Program Interface Version 2, Update 1
Extracted elements (33)
Credential references are always indirect, mediated by GSS-API implementations via cred_handles, never requiring callers to access credential elements directly. This isolates callers from mechanism-specific credential formats and enables the GSS-API implementation to enforce access controls on behalf of the underlying security mechanisms.
GSS-API defines no initialization calls, requiring implementations to be self-initializing. This avoids requiring callers to invoke setup routines before using the API, improving application portability and eliminating a class of usage errors.
GSS-API treats names as opaque objects rather than prescribing naming structures, supporting implementability atop a range of underlying security mechanisms that process names in different forms. Generalized name translation services are explicitly outside GSS-API scope; local conversion functions are anticipated.
prot_ready_state achieves full backward compatibility with GSS-V1 callers: V1 callers unaware of prot_ready_state receive expected behavior from GSS_S_COMPLETE without early per-message access, while V2 callers can optionally use per-message protection before full context establishment, enabling pipelined data transfer during handshakes.
Appendix B documents compatibility with GSS-V1: GSS-V2 adds GSS_Add_cred, GSS_Inquire_cred_by_mech, GSS_Export/Import_sec_context, GSS_Wrap_size_limit, GSS_Inquire_context, GSS_Export_name, GSS_Duplicate_name, GSS_Canonicalize_name, and GSS_Inquire_mechs_for_name calls. The prot_ready_state, trans_state, and anon_state context attributes are also new. GSS-V1 callers remain unaffected by these additions.
GSS-API tokens defined for a particular mechanism may not be interoperable with non-GSS-API callers of the same underlying cryptographic technology, because token formats and protocol integration techniques may differ. A peer using the same underlying technology outside the GSS-API paradigm is not guaranteed to interoperate with a GSS-API peer.
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. This is an explicit exception to the general rule that mechanisms may enable unrequested services.
For QOP interoperability, mechanisms allowing optional support of particular QOP values must satisfy one of: (i) all implementations can process messages protected with any QOP value regardless of send capability, or (ii) mutually-supported receiver QOP values are determined during context establishment and only those values are used for message protection.
GSS-API callers desiring per-message security services must check integ_avail and conf_avail flags returned at context establishment time. A FALSE integ_avail means GSS_GetMIC() and GSS_Wrap() will apply no cryptographic protection to user data messages; conf_avail will never be TRUE unless integ_avail is also TRUE.
Mechanisms supporting optional services must send at least one token from acceptor to initiator during context establishment when the initiator requests such a service, so that the initiating GSS-API can correctly indicate whether the acceptor supports the requested service.
Support for the default credential resolution algorithm for initiator credentials (GSS_Init_sec_context with GSS_C_NO_CREDENTIAL) is mandated. The algorithm proceeds through four ordered steps: (i) single authorized principal, (ii) platform default network identity, (iii) mapped local identity, (iv) user-configurable default. Failure returns GSS_S_NO_CRED.
When prot_ready_state is returned TRUE, mechanisms shall also set all context service indicator flags (deleg_state, mutual_state, replay_det_state, sequence_state, anon_state, trans_state, conf_avail, integ_avail) that represent facilities confirmed to be available on the context at that time.
Zero-length tokens are never returned by GSS routines for transfer to a peer. Context-level tokens may be output by GSS-API calls whether or not calls indicate successful completion; per-message tokens are to be returned only upon successful per-message call completion.
A GSS-API credential structure may contain multiple credential elements, each containing mechanism-specific information for a particular mech_type, all representing a common entity. Multiple credential elements with overlapping combinations of mechanism, usage mode, and validity period are not permitted within a single credential structure.
Channel bindings (chan_binding) allow callers to bind security context establishment to characteristics of the underlying communications channel such as addresses or transformed representations of encryption keys, limiting the scope within which an intercepted token can be reused. Both initiator and acceptor must provide consistent channel binding values for validation to succeed.
GSS-API defines four call groups: credential management (GSS_Acquire_cred, GSS_Release_cred, GSS_Inquire_cred, GSS_Add_cred, GSS_Inquire_cred_by_mech), context-level calls (GSS_Init_sec_context, GSS_Accept_sec_context, GSS_Delete_sec_context, etc.), per-message calls (GSS_GetMIC, GSS_VerifyMIC, GSS_Wrap, GSS_Unwrap), and support calls (GSS_Display_status, GSS_Indicate_mechs, name manipulation routines).
GSS-API supports three name forms: INTERNAL NAME (opaque, implementation-defined), contiguous OCTET STRING tagged with a namespace OID, and the Exported Name Object (a flat binary form identified by GSS_C_NT_EXPORT_NAME, generated by GSS_Export_name(), suitable for direct memcmp() comparison in access control lists). A Mechanism Name (MN) is an INTERNAL NAME guaranteed to correspond to exactly one mechanism.
Interprocess context transfer (new in GSS-V2) is provided by GSS_Export_sec_context and GSS_Import_sec_context, allowing a context to move between processes on a single machine. After successful export, the original context handle is invalidated; the adopting process passes the inter-process token to GSS_Import_sec_context to obtain a functionally identical context. Support is optional and indicated by trans_state=TRUE at context creation.
Major status codes are divided into fatal error codes (GSS_S_BAD_BINDINGS, GSS_S_BAD_MECH, GSS_S_BAD_NAME, GSS_S_BAD_NAMETYPE, GSS_S_BAD_SIG/GSS_S_BAD_MIC, GSS_S_CONTEXT_EXPIRED, GSS_S_CREDENTIALS_EXPIRED, GSS_S_DEFECTIVE_CREDENTIAL, GSS_S_DEFECTIVE_TOKEN, GSS_S_FAILURE, GSS_S_NO_CONTEXT, GSS_S_NO_CRED, GSS_S_BAD_QOP, GSS_S_UNAUTHORIZED, GSS_S_UNAVAILABLE, GSS_S_DUPLICATE_ELEMENT, GSS_S_NAME_NOT_MN) and informatory codes (GSS_S_COMPLETE, GSS_S_CONTINUE_NEEDED, GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN, GSS_S_UNSEQ_TOKEN, GSS_S_GAP_TOKEN).
Mechanism types are identified by ASN.1 Object Identifiers (OIDs) per [ISOIEC-8824]/[ISOIEC-8825] and embody a specific cryptographic technology plus the syntax and semantics of data element exchanges. The Kerberos V5 mechanism OID is 1.2.840.113554.1.2.2; DASS is 1.3.12.2.1011.7.5. Hierarchically-structured OIDs prevent ambiguous mech_type interpretation.
Optional context services are requested via req_flags to GSS_Init_sec_context: delegation, mutual authentication, replay detection, out-of-sequence detection, anonymous authentication, per-message confidentiality availability, and per-message integrity availability. ret_flags from both GSS_Init_sec_context and GSS_Accept_sec_context indicate which services will actually be available on the established context.
prot_ready_state is a Boolean (new in GSS-V2) returned by GSS_Init_sec_context, GSS_Accept_sec_context, and GSS_Inquire_context. When TRUE (possibly before GSS_S_COMPLETE), per-message protection via GSS_Wrap/GSS_Unwrap/GSS_GetMIC/GSS_VerifyMIC is available. Mutual authentication is not guaranteed until GSS_S_COMPLETE is returned.
Security contexts are established between peers using local or delegated credentials. Multiple contexts may coexist between a pair of peers using the same or different credentials, enabling graceful rollover when credentials expire. GSS-API implementations retain inquirable context data until explicitly released, even after context expiration.
Tokens are divided into context-level tokens (exchanged to establish and manage a security context) and per-message tokens (protecting data messages on established contexts). The first context-level token from GSS_Init_sec_context must begin with a globally-interpretable mechanism OID; all remaining token content is mechanism-specific and opaque to callers.
Section 4 defines GSS-API Name Type OIDs: NT_USER_NAME (1.3.6.1.5.6.1), NT_MACHINE_UID_NAME (1.3.6.1.5.6.2), NT_STRING_UID_NAME (1.3.6.1.5.6.3), NT_HOSTBASED_SERVICE (1.3.6.1.5.6.2 — host-based service name), NT_ANONYMOUS (1.3.6.1.5.11.3 — anonymous principal), and GSS_C_NT_EXPORT_NAME (1.3.6.1.5.6.4 — exported name object). These OIDs are defined within the GSS-API namespace.
Anonymity support allows a context initiator to request via anon_req_flag that its identity not be revealed to the context acceptor. Mechanisms are not required to honor this request; the caller is informed via the returned anon_state indicator whether the request was honored. Authentication as the anonymous principal (Section 4.5 OID) does not necessarily eliminate credential requirements.
Section 6 notes that quality of security services provided depends on the strength and correct implementation of underlying mechanisms. Callers should not assume confidentiality protection for channel binding information; mechanisms are encouraged but not required to provide it.
The ability for an entity to acquire and use credentials associated with a given identity is equivalent to that entity's ability to successfully assert that principal's identity. Underlying mechanisms and OS functions must constrain credential acquisition to appropriate processes; this responsibility must be taken seriously by implementors.
The inter-process context token produced by GSS_Export_sec_context may contain sensitive data from the original security context, including cryptographic keys. Applications using inter-process tokens must take appropriate steps to protect these tokens in transit between processes.
Context establishment is driven by iterative calls to GSS_Init_sec_context and GSS_Accept_sec_context. States: GSS_S_CONTINUE_NEEDED (additional token exchanges required; caller loops), prot_ready_state=TRUE (per-message protection available mid-establishment), and GSS_S_COMPLETE (full context established, mutual authentication guaranteed if requested). Sequencing-related codes during establishment are always fatal (accompany GSS_S_FAILURE only).
Per-message replay/sequencing state machine produces five outcomes for well-formed, correctly signed messages when replay_det_state or sequence_state is TRUE: GSS_S_COMPLETE (fresh, in-order), GSS_S_DUPLICATE_TOKEN (replay detected), GSS_S_OLD_TOKEN (beyond window), GSS_S_UNSEQ_TOKEN (earlier in sequence than already-processed message), GSS_S_GAP_TOKEN (predecessor messages missing). Detection does not prevent delivery; action is caller policy.
Section 3.1 defines the Mechanism-Independent Token Format for the initial context-level token: a DER-encoded ASN.1 Application tag (0x60) and length field, followed by a DER-encoded OID identifying the mechanism (mech_type), followed by mechanism-specific token data. Only the initial token carries this header; all subsequent tokens are entirely mechanism-specific.
Section 3.2 defines the Mechanism-Independent Exported Name Object Format: a header containing a 2-byte token identifier (0x04 0x01), a 2-byte OID length, the DER-encoded mechanism OID, a 4-byte name length, and the mechanism-specific name bytes. This blob is generated by GSS_Export_name() and supports direct binary comparison for ACL lookups.