Generic Security Service API : C-bindings
obsoleted by
- rfc-2744 — Generic Security Service API Version 2 : C-bindings
Extracted elements (27)
Credential acquisition may be deferred by the mechanism until the credential is actually needed at context-establishment time. This design choice is implementation-specific and must be invisible to the caller; it avoids unnecessary credential-fetch overhead when credentials are acquired but not immediately used.
Name comparison is performed on internal-form names via gss_compare_name rather than requiring applications to parse printable name syntax. This decouples applications from the multiple namespace syntaxes a GSSAPI implementation may support and provides a canonical equivalence check.
The credential handle (gss_cred_id_t) is an opaque value that intentionally contains no security-relevant information and requires no special protection by the application. GSSAPI never exposes actual credential data to applications; the handle merely identifies internal GSSAPI state, and a given handle value may refer to different credentials when presented by different callers.
The gss_OID_desc datatype is equivalent to the X/Open OM_object_identifier datatype, and platforms supporting the xom.h X/Open header may use it for the definitions of OM_uint32 and gss_OID_desc. Individual GSSAPI implementations may augment the standard routine set with mechanism-specific extensions for functionality unavailable in the generic forms.
A call to gss_inquire_cred immediately following gss_acquire_cred must return valid credential data, even if the implementation defers actual credential acquisition until context establishment time. The deferred-acquisition optimization must be invisible to the calling application.
Applications are encouraged on portability grounds to use the generic GSSAPI routines wherever possible and to accept the default security mechanism (GSS_C_NULL_OID) rather than requesting a specific mechanism. Callers are likewise encouraged to accept the default quality of protection (GSS_C_QOP_DEFAULT) offered by the chosen mechanism.
Applications should treat gss_OID_desc values returned by GSSAPI routines as read-only and must not attempt to deallocate them. gss_OID values returned by gss_indicate_mechs and gss_accept_sec_context point into static storage and must also be treated as read-only.
GSSAPI implementations must impose a local access-control policy on callers of gss_acquire_cred to prevent unauthorized callers from acquiring credentials to which they are not entitled.
The minor_status parameter must always be set by a GSSAPI routine, even when the routine returns a calling error or a generic fatal API error. Output pointer parameters must always be set (possibly to NULL) even on error; associated length fields must be set to zero when no storage was allocated.
gss_accept_sec_context accepts a remotely-initiated security context. It returns the authenticated src_name, mech_type, ret_flags, and, when GSS_C_DELEG_FLAG is set, a delegated_cred_handle. The parameters src_name, ret_flags, time_rec, and delegated_cred_handle are undefined unless the routine returns GSS_S_COMPLETE.
gss_acquire_cred acquires a handle for a pre-existing credential by desired_name, requested lifetime, desired mechanisms, and usage (GSS_C_BOTH, GSS_C_INITIATE, or GSS_C_ACCEPT). It returns an output_cred_handle, actual_mechs, and the actual validity period time_rec. The routine is not a network-login function; it acquires handles to existing credentials only.
gss_channel_bindings_t binds a security context to a communications channel. The structure holds initiator_addrtype, initiator_address, acceptor_addrtype, acceptor_address, and application_data fields. The mechanism signs the concatenation of these fields and binds the signature to the context-establishment token emitted by gss_init_sec_context.
gss_delete_sec_context deletes local context data structures and generates an output_token that, when passed to the peer's gss_process_context_token, instructs it to also delete the context. No further security services may be obtained via the deleted context handle.
gss_display_status converts a GSS or mechanism-specific status code to human-readable text. Because a single status value may encode multiple errors, callers may need to invoke it multiple times: message_context is initialized to 0 and returns non-zero when additional messages remain in the same status_value.
gss_init_sec_context initiates security context establishment with a remote peer. It consumes an input_token (GSS_C_NO_BUFFER on first call), optional channel bindings, req_flags, and target_name, and returns an output_token for transfer to the acceptor plus ret_flags indicating which services the established context actually supports.
gss_OID (gss_OID_desc) represents an ASN.1 BER-encoded object identifier, with an OM_uint32 length and a void* elements pointer to the encoded bytes. It is used to select underlying security mechanisms and name types. Applications must treat gss_OID_desc values returned by GSSAPI as read-only and must not attempt to deallocate them.
gss_OID_set (gss_OID_set_desc) aggregates multiple OIDs via an int count and a gss_OID elements pointer to an array of gss_OID_desc objects. It is used to enumerate available mechanisms, requested mechanisms, and per-credential supported mechanisms. Storage is freed via gss_release_oid_set.
gss_seal signs and optionally encrypts a message. conf_req_flag=true requests confidentiality plus integrity; false requests integrity only. The output_message_buffer contains both the protected data and the signature. conf_state reports whether confidentiality was actually applied.
gss_sign generates a cryptographic signature token for a supplied message using the specified context and qop_req (quality-of-protection, defaulting to GSS_C_QOP_DEFAULT). The resulting msg_token is transferred to the peer and verified via gss_verify.
gss_verify and gss_unseal check signatures and decrypt sealed messages, returning qop_state (protection strength) and, for gss_unseal, conf_state (whether confidentiality was used). Both return GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN, or GSS_S_UNSEQ_TOKEN for replay and sequencing violations.
OM_uint32 is a portable 32-bit unsigned integer type used throughout the C bindings wherever a guaranteed minimum bit-count is important. Individual implementations provide appropriate typedef mappings onto a built-in type.
Six independent boolean context service flags are defined as bit-mask constants: GSS_C_DELEG_FLAG (1), GSS_C_MUTUAL_FLAG (2), GSS_C_REPLAY_FLAG (4), GSS_C_SEQUENCE_FLAG (8), GSS_C_CONF_FLAG (16), and GSS_C_INTEG_FLAG (32). They are requested in req_flags and reported back in ret_flags by both gss_init_sec_context and gss_accept_sec_context.
The gss_buffer_desc structure (typedef'd as gss_buffer_t) is the universal carrier for multi-byte data in the C bindings. It contains a size_t length field and a void* value pointer. Storage returned to the application by GSSAPI routines must be freed via gss_release_buffer.
The GSS status code supplementary-info field defines four bits: GSS_S_CONTINUE_NEEDED (bit 0) signals the routine must be called again; GSS_S_DUPLICATE_TOKEN (bit 1), GSS_S_OLD_TOKEN (bit 2), and GSS_S_UNSEQ_TOKEN (bit 3) report replay and sequencing anomalies without necessarily failing the call.
Applications must not use confidential data as channel-binding components because some mechanisms include the actual channel binding data in the context-establishment token rather than just a signature over it. If channel bindings presented to gss_accept_sec_context differ from those supplied to gss_init_sec_context, GSS_S_BAD_BINDINGS is returned and the context is not established.
Context establishment is a multi-round token exchange: initial state (input_token = GSS_C_NO_BUFFER) → token-exchange loop triggered by GSS_S_CONTINUE_NEEDED (re-call with peer-supplied token) → complete (GSS_S_COMPLETE). Both gss_init_sec_context and gss_accept_sec_context participate in this loop; the context_handle is allocated on the first call and reused in continuation calls.
The GSS status code is a 32-bit OM_uint32 value partitioned into three fields: calling error (bits 31–24), routine error (bits 23–16), and supplementary info (bits 15–0). If either upper 16-bit field is non-zero the call failed. Symbol values such as GSS_S_BAD_NAMETYPE are complete 32-bit codes with the field value already shifted to its correct bit position.