Generic Security Service Application Program Interface
obsoleted by
- rfc-2078 — Generic Security Service Application Program Interface, Version 2
Extracted elements (26)
Callers desiring portability across alternative printable name syntaxes should use GSS_Compare_name() rather than string comparison of printable forms. GSS_Import_name() may support multiple printable syntaxes for the same namespace, so printable equality does not imply name equality.
GSS-API achieves mechanism independence by defining a generic interface abstracting over both secret-key (e.g., Kerberos) and public-key (e.g., X.509) cryptographic technologies, allowing source-level portability of calling applications across different security environments without code changes.
GSS-API's security context construct is deliberately independent of communications protocol associations, allowing a single implementation to be used by multiple protocol modules. No correlation between security context and protocol association is mandated, enabling use across both connection-oriented and connectionless environments.
GSS_CONTINUE_NEEDED status returns allow multi-message authentication sequences of different underlying mechanisms to be handled uniformly without separate code paths in callers. Continuation calls to GSS_Init_sec_context() and GSS_Accept_sec_context() also encapsulate mutual authentication within the context initiation calls.
GSS-API callers desiring per-message security services must check the values of integ_avail and conf_avail flags at context establishment time, and must be aware that a FALSE integ_avail value means GSS_Sign() or GSS_Seal() invocations will apply no cryptographic protection to user data.
It is highly recommended that mech_types supporting replay detection and sequencing features allow them to be activated selectively on initiator request, since these features may interfere with certain applications' intended communications paradigms and are likely resource-intensive.
It is recommended that callers initiating contexts specify the 'default' mech_type value, allowing system-specific functions within or invoked by the GSS-API implementation to select the appropriate mech_type.
It is strongly recommended that GSS-API callers provide channel bindings consistent with mechanism conventions and the networking environment in which they operate, in order to achieve the full security functionality available from each mechanism.
At context establishment, two boolean flags are returned: integ_avail indicates whether per-message integrity and data origin authentication services are available; conf_avail indicates whether per-message confidentiality is available. The conf_avail flag will never be TRUE unless integ_avail is also TRUE.
Channel bindings (chan_binding) allow callers to bind security context establishment to characteristics of the underlying communications channel such as addresses or transformed encryption keys. Both peers must provide consistent channel binding values; the caller must determine chan_binding values before calling GSS_Init_sec_context().
Each GSS-API call returns a major_status (mechanism-independent indication such as GSS_COMPLETE, GSS_FAILURE, GSS_CONTINUE_NEEDED) and a minor_status (mechanism-specific detail, not defined by this specification). Fatal error codes include GSS_BAD_BINDINGS, GSS_BAD_MECH, GSS_BAD_SIG, GSS_DEFECTIVE_TOKEN, GSS_NO_CRED, and others; informatory codes include GSS_DUPLICATE_TOKEN, GSS_OLD_TOKEN, and GSS_UNSEQ_TOKEN.
GSS_Accept_sec_context() inputs include acceptor_cred_handle, input_context_handle (0 for first call), chan_bindings, and input_token. Outputs include src_name (authenticated peer identity), mech_type, context state flags, delegated_cred_handle (significant only when deleg_state is TRUE), and output_token for mutual authentication continuation.
GSS_Acquire_cred() acquires credentials for a principal via inputs desired_name (NULL for default), lifetime_req, desired_mechs (empty set for system default), and cred_usage (0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, 2=ACCEPT-ONLY), returning a cred_handle, actual_mechs, and lifetime_rec. Single-user clients using default credentials typically need not invoke this call.
GSS-API uses two name representation classes: a printable form (OCTET STRING) tagged with an OID identifying the namespace, used for user-facing input/output; and an internal form (INTERNAL NAME) opaque to callers, defined by the GSS-API implementation. OID tagging prevents name aliasing across different namespace types.
GSS_Init_sec_context() inputs include claimant_cred_handle, input_context_handle (0 for first call), targ_name, mech_type, request flags (deleg_req_flag, mutual_req_flag, replay_det_req_flag, sequence_req_flag), lifetime_req, chan_bindings, and input_token. Outputs include output_token, output_context_handle, state indicators, conf_avail, integ_avail, and lifetime_rec.
GSS_Seal() performs data origin authentication, integrity, and optionally confidentiality (when conf_req_flag is TRUE) on input_message, producing a single encapsulated output_message. GSS_Unseal() reverses this, deciphering if needed, validating integrity, and returning plaintext output_message along with conf_state and qop_state.
GSS_Sign() applies a data origin authentication signature to a message using the referenced context and qop_req, returning a separate per_msg_token. GSS_Verify() validates the per_msg_token against the message, applies replay detection and sequencing if enabled, and returns qop_state indicating the protection quality applied.
Mechanism types (mech_types) are represented as ASN.1 Object Identifiers (OIDs) as specified in ISO/IEC 8824 and 8825. OIDs qualify token interpretation between peers; for example, the DASS MechType OID is 1.3.12.2.1011.7.5. Hierarchical OID structure precludes ambiguous interpretation.
Per-message replay detection and sequencing are optionally selectable features controlled at context initiation by replay_det_req_flag and sequence_req_flag. When active, GSS_Verify()/GSS_Unseal() return GSS_DUPLICATE_TOKEN for detected duplicates, GSS_OLD_TOKEN for messages outside the detection window, and GSS_UNSEQ_TOKEN for out-of-order messages. Detection does not prevent delivery; appropriate action is a caller policy matter.
Quality of Protection (QOP) is a per-message integer parameter (qop_req = 0 selects default) allowing callers to trade security processing overhead against protection requirements. Non-default QOP values are mechanism-specific and non-portable; meaningful use requires familiarity with the underlying mechanism's QOP definitions.
Tokens are divided into two classes: context-level tokens exchanged to establish and manage a security context, and per-message tokens exchanged on an established context to provide protective services for data. Tokens are opaque to GSS-API callers and are generated and processed solely by the GSS-API implementation.
Channel binding mismatch (GSS_BAD_BINDINGS) indicates a security-relevant event, preventing context establishment. Verification of chan_binding information provided by the remote peer protects against various active attacks by binding context establishment to channel-specific characteristics that an attacker cannot spoof.
Credential establishment, particularly for interactive users, requires access to passwords or other sensitive material that should be exposed for the shortest time possible. Preliminary credential establishment should be performed through local means at login time with results cached for subsequent GSS_Acquire_cred() access, minimizing exposure of sensitive authentication material.
The ability for an entity to acquire and use credentials associated with a given identity is equivalent to the ability to assert that principal's identity. Underlying mechanisms and OS functions below the GSS-API are responsible for constraining credential acquisition and use to appropriate processes; implementors must treat this responsibility seriously.
Security context establishment: initiator calls GSS_Init_sec_context() producing output_token (state: INITIATING); target calls GSS_Accept_sec_context() returning GSS_COMPLETE or GSS_CONTINUE_NEEDED (state: ACCEPTING); if mutual_state is TRUE, target's output_token triggers a continuation call to GSS_Init_sec_context() (state: COMPLETING). Both sides reach ESTABLISHED when GSS_COMPLETE is returned. Deletion via GSS_Delete_sec_context() transitions to DELETED; GSS_Process_context_token() processes peer deletion notifications.
Appendix B defines a uniform token encapsulation format for GSS-API mechanism designers, encoding mechanism-specific content together with a globally-interpretable mechanism identifier (OID). This wrapping allows peers to unambiguously identify the mechanism associated with a received token.