Generic Security Service Application Program Interface, Version 2
obsoleted by
- rfc-2743 — Generic Security Service Application Program Interface Version 2, Update 1
obsoletes
- rfc-1508 — Generic Security Service Application Program Interface
Extracted elements (30)
GSS-API is designed to be mechanism-independent, supporting both secret-key (e.g., Kerberos) and public-key (e.g., X.509) cryptographic technologies under a single interface. This allows source-level portability of applications across different security environments without requiring separate code paths.
GSS-API treats names as opaque objects rather than prescribing naming structures, specifically to support the range of underlying mechanisms that authenticate different name forms. Name manipulation primitives (GSS_Compare_name, GSS_Display_name, GSS_Import_name) are included in the API for portability across naming environments.
No initialization calls are defined in GSS-API; implementations must be self-initializing. This simplifies caller code by eliminating mandatory setup sequences before invoking any GSS-API facility.
Per-message replay detection and sequencing are selectable by the context initiator via flags (replay_det_req_flag, sequence_req_flag) rather than always enabled, because these features may interfere with certain applications' communications paradigms and are resource-intensive; not all mechanism types support them.
prot_ready_state was introduced in GSS-V2 to achieve full, transparent backward compatibility with GSS-V1 callers: V1 callers ignore prot_ready_state and still get correct behavior at GSS_S_COMPLETE, while V2 callers can optionally begin per-message protection earlier when the session key is already available.
Appendix B documents compatibility between GSS-V2 (RFC 2078) and GSS-V1 (RFC 1508). GSS-V1 callers need not know about prot_ready_state and receive expected behavior via GSS_S_COMPLETE; however, GSS-V2 implementations may support GSS-V1 mechanism code that never returns TRUE prot_ready_state.
Callers must be aware that a returned FALSE value for integ_avail means that invocation of GSS_GetMIC() or GSS_Wrap() on the associated context will apply no cryptographic protection to user data messages.
Consistent channel binding values must be provided to both GSS_Init_sec_context() by the initiator and GSS_Accept_sec_context() by the target, in order for both peers' GSS-API mechanisms to validate that received tokens possess correct channel-related characteristics.
If a token presented for processing on a GSS-API security context is determined to be invalid, the context's state should not be disrupted for purposes of processing subsequent valid tokens.
It is strongly recommended that GSS-API callers provide channel bindings consistent with the conventions of the networking environment in order to be portable across multiple mechanisms and achieve full security functionality.
The conf_avail flag will never be returned TRUE unless the integ_avail flag is also returned TRUE. Callers desiring per-message security services must check these flags at context establishment time.
The first context-level token from GSS_Init_sec_context() is required to indicate at its very beginning a globally-interpretable mechanism identifier (OID) of the security mechanism. Remaining tokens' contents are mechanism-specific and opaque to callers.
When prot_ready_state is returned TRUE, mechanisms shall also set those context service indicator flags (deleg_state, mutual_state, replay_det_state, sequence_state, anon_state, trans_state, conf_avail, integ_avail) which represent facilities confirmed available on the context at that time.
Whenever possible, GSS_Delete_sec_context() calls should be successfully processable even if other calls cannot succeed, enabling context-related resources to be released. Failing calls should free any memory they allocate so callers may retry.
A GSS-API credential structure may contain multiple credential elements, each with mechanism-specific information for a particular mech_type, but all representing a common entity. Multiple credential elements with overlapping combinations of mechanism, usage mode (INITIATE-ONLY, ACCEPT-ONLY, INITIATE-AND-ACCEPT), and validity period within a single credential are not permitted.
Anonymity support is provided via the anon_req_flag input to GSS_Init_sec_context(), which requests that the initiator's identity not be provided to the acceptor. The OID {1.3.6.1.5.6.3} (symbolic name GSS_C_NT_ANONYMOUS) identifies anonymous names in a mechanism-independent fashion.
Channel bindings (chan_binding) are caller-provided data that bind context establishment to characteristics of the underlying communications channel (e.g., addresses, encryption keys). They strengthen peer entity authentication by limiting the reuse scope of intercepted context-establishment tokens.
GSS_Accept_sec_context() accepts an inbound security context from a peer, consuming the input_token produced by GSS_Init_sec_context(). Returns src_name (the authenticated initiator identity), delegated_cred_handle if delegation was granted, and an optional output_token for mutual authentication. Returns GSS_S_CONTINUE_NEEDED if further exchanges are required.
GSS-API major_status codes are divided into fatal error codes (e.g., GSS_S_BAD_BINDINGS, GSS_S_BAD_MECH, GSS_S_BAD_SIG, GSS_S_DEFECTIVE_TOKEN, GSS_S_FAILURE) 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). A separate minor_status provides mechanism-specific detail.
GSS_Export_sec_context() and GSS_Import_sec_context() enable transfer of an active security context between processes on an end system, supporting multi-process server architectures. The exporting call deactivates the context locally and produces an interprocess transfer token.
GSS_GetMIC() and GSS_VerifyMIC() provide per-message data origin authentication and integrity as a MIC token separate from the message data. GSS_GetMIC() takes a message and returns a per-message token; GSS_VerifyMIC() validates that token against the corresponding message.
GSS_Init_sec_context() initiates an outbound security context. Inputs include claimant_cred_handle, targ_name, mech_type, and Boolean flags for delegation (deleg_req_flag), mutual authentication (mutual_req_flag), replay detection (replay_det_req_flag), sequencing (sequence_req_flag), and anonymity (anon_req_flag). Returns output_token and corresponding state indicator Booleans plus prot_ready_state.
GSS_Wrap() and GSS_Unwrap() provide per-message integrity and optional confidentiality with encapsulation. GSS_Wrap() signs, optionally encrypts, and encapsulates the message; GSS_Unwrap() decapsulates, decrypts if needed, and validates integrity. A conf_req_flag input selects confidentiality.
Quality of Protection (QOP) is a per-message parameter allowing callers to select among protection options offered by a multi-QOP mechanism. Most callers should request default QOP; non-default QOP values are mechanism-specific, non-portable, and unsupported values yield GSS_S_BAD_QOP.
The prot_ready_state Boolean, new in GSS-V2, is returned by GSS_Init_sec_context(), GSS_Accept_sec_context(), and GSS_Inquire_context(). When TRUE, per-message protection via GSS_Wrap/Unwrap/GetMIC/VerifyMIC is available even before GSS_S_COMPLETE is returned, allowing message protection during context establishment.
Callers should not assume that underlying mechanisms provide confidentiality protection for channel binding information. Channel binding data may be exposed in tokens even when the binding is intended to prevent token reuse by attackers.
The ability for an entity to acquire and use credentials associated with a given identity is equivalent to that entity's ability to assert that principal's identity; underlying mechanisms and OS functions must constrain credential acquisition to appropriate processes. Implementors are directed to take this responsibility seriously.
Security context establishment follows a loop driven by GSS_S_CONTINUE_NEEDED: the initiator calls GSS_Init_sec_context(), sends the output_token to the target, which calls GSS_Accept_sec_context(); if either returns GSS_S_CONTINUE_NEEDED, the resulting token is returned and the call is repeated until both sides return GSS_S_COMPLETE.
The Mechanism-Independent Exported Name Object format (Section 3.2) provides a canonical flat binary representation of a mechanism-specific name suitable for binary comparisons and use in access control lists. It is produced by GSS_Export_name() and accepted by GSS_Import_name().
The mechanism-independent token format (Section 3.1) wraps the first context-level token with an ASN.1/BER-encoded header containing a tag (0x60), length, and an OID identifying the mechanism type, followed by mechanism-specific token content. This ensures global interpretability of the first token.