Generic Security Service Application Program Interface (GSS-API) Extension for Storing Delegated Credentials
Extracted elements (16)
GSS_Store_cred() was introduced because delegated credential handles have no path into the implicit credential store, limiting acceptors to direct use with only GSS_Init_sec_context(), GSS_Inquire_cred*(), and GSS_Release_cred(). On Unix systems, a call to exec() obliterates any delegated credential handle in the process, making delegation effectively useless across process boundaries.
The GSS-API does not provide credential import/export interfaces analogous to its context import/export interfaces, and there is no mechanism for delegated credential handles to be made available for acquisition via GSS_Acquire_cred()/GSS_Add_cred(). This asymmetry motivates the new primitive.
The C-bindings for GSS_Store_cred() are designed based on the style of the GSS-APIv2 C-Bindings (RFC 2744) and make use of types from that specification, ensuring consistency with the existing GSS-API C-binding conventions.
If default_cred is TRUE and the credential can be successfully stored, the implementation SHOULD store it as the default credential.
If the current credential store has no default credential, the implementation MAY make the stored credentials available as the default credential regardless of the value of default_cred.
The input_cred_handle argument to GSS_Store_cred() MUST NOT be GSS_C_NO_CREDENTIAL; a real credential handle must be supplied.
When a non-GSS_C_NULL_OID desired_mech_element is provided and the major status is not GSS_S_COMPLETE, the minor status output SHOULD carry a mechanism-specific value to aid diagnostics.
GSS_Store_cred() defines six major_status return codes: GSS_S_COMPLETE (success), GSS_S_CREDENTIALS_EXPIRED (expired credentials), GSS_S_NO_CRED (no input credentials), GSS_S_UNAVAILABLE (store not available), GSS_S_DUPLICATE_ELEMENT (principal exists and overwrite_cred is FALSE), and GSS_S_FAILURE (other failure).
GSS_Store_cred() is a new GSS-API primitive that stores a given credential (delegated or otherwise) into the current implicit credential store. It accepts input_cred_handle, cred_usage, desired_mech_element, overwrite_cred, and default_cred as inputs, and returns major_status, minor_status, mech_elements_stored, and cred_usage_stored.
The C-binding is gss_store_cred() with signature: OM_uint32 gss_store_cred(OM_uint32 *minor_status, gss_cred_id_t input_cred_handle, gss_cred_usage_t cred_usage, const gss_OID desired_mech, OM_uint32 overwrite_cred, OM_uint32 default_cred, gss_OID_set *elements_stored, gss_cred_usage_t *cred_usage_stored). The boolean arguments overwrite_cred and default_cred are typed as OM_uint32, with 0=FALSE and non-zero=TRUE.
The cred_usage input parameter controls what usage of the credential is stored: 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, 2=ACCEPT-ONLY. The corresponding output cred_usage_stored indicates what was actually stored.
The default_cred boolean is an advisory input; if TRUE, the implementation SHOULD make the stored credential available as the default credential (usable with GSS_C_NO_NAME or GSS_C_NO_CREDENTIAL).
The desired_mech_element input is an OID; if GSS_C_NULL_OID, all mechanism elements of the credential are stored. If a specific OID is provided, only that mechanism's element is stored.
The overwrite_cred boolean input controls whether an existing credential for the same principal in the store is replaced. If FALSE and a matching credential exists, GSS_S_DUPLICATE_ELEMENT is returned.
Acceptor applications MUST only store delegated credentials into appropriate credential stores and only after proper authorization of the authenticated initiator principal to the requested service(s). Storing delegated credentials without authorization would allow privilege escalation.
Acceptor applications that have no use for delegated credentials MUST release them. In the GSS-API C-Bindings, this can be done by providing a NULL value for the delegated_cred_handle argument to gss_accept_sec_context(). Retaining unused delegated credentials is an unnecessary security risk.