Projects/Credential Store extensions

This project was completed in release 1.11.

This project is about adding a set of extensions to GSSAPI to specify credential locations in a mechanism-agnostic way.

Background

During the development of the GSS-Proxy project in connection with the Projects/ProxyGSSAPI project it became evident that the application implementing the proxy needs to be able to be configured to use different credentials depending on what application is connecting to the proxy. Using the normal defaults of GSSAPI, this not possible, because the proxy application does not run in the same process environment as the proxied application, and may run multiple concurrent tasks on behalf of different applications with different trust/credentials.

A method to pass a set of default credentials to use on behalf of these application is necessary. This method should not be mechanism-specific, as the proxy tries to be mechanism-agnostic as much as possible.

In this light a 'Credential Stores' Extension has been proposed on the Kitten IETF Mailing list.

Requirements

• Abstract interface to pass credential store configuration to GSSAPI mechanisms.
• The credentials need to be specified in configuration files, so security sensitive information (like passwords) must not be exposed there.
• Mechanisms can define their own key/value pairs.
• New Key/Value pairs can be easily added in future.
• The mechglue need not to know how to interpret key/value pairs; they are interpreted only by mechanisms.

Architecture

The exposed public functions are paired with analogous functions in the mechglue SPI to give mechanisms access to the Credentials Store. gss_add_cred_from is not included in the SPI since the mechglue does not invoke it. Implementations of gss_acquire_cred_from are provided for krb5 and SPNEGO, and an implementation of gss_store_cred_into is provided for krb5.

New APIs

Functions:

• gss_acquire_cred_from()
• gss_add_cred_from()
• gss_store_cred_into()

Structures:

• gss_key_value_element_struct
• gss_key_value_set_struct

If the cred store structure does not contain a mechanism-specific configuration for the mechanism at hand, the usual defaults are applied.

gss_acquire_cred_from()

Acquires new credentials using the provided store. The store can specify both the actual credentials and/or the credential location. In the krb5 mechanism case it could specify a keytab and a ccache location.

gss_add_cred_from()

Same as above, but can target a specific mechanism. The credential store need not be mechanism-specific and remains abstract.

gss_store_cred_into()

This is analogous to gss_cred_store() except that a specific credential store can be specified (in the krb5 case, generally a ccache file).

gss_key_value_element_struct

A key/value pair. Keys are either URIs or implementation-specific short strings (which must not contain a colon). Example: URN = 'ccache' Value = 'FILE:/tmp/somecc'

gss_key_value_set_struct

A counter and an array of elements.

C bindings

/* Extension for credential stores */
struct gss_key_value_element_struct {
    const char *key;
    const char *value;
};
typedef struct gss_key_value_element gss_key_value_element_desc;

struct gss_key_value_set_struct {
    OM_uint32 count;
    gss_cred_store_element_t *elements;
};
typedef struct gss_key_value_set_struct gss_key_value_set_desc;
typedef const struct gss_key_value_set_struct *gss_const_key_value_set_t;

#define GSS_C_NO_CRED_STORE ((gss_const_cred_store_t) 0)

OM_uint32 gss_acquire_cred_from(
            OM_uint32 *minor_status,
            gss_name_t desired_name,
            OM_uint32 time_req,
            gss_OID_set desired_mechs,
            gss_cred_usage_t cred_usage,
            gss_const_key_value_set_t cred_store,
            gss_cred_id_t *output_cred_handle,
            gss_OID_set *actual_mechs,
            OM_uint32 *time_rec);

OM_uint32 gss_add_cred_from (
            OM_uint32 *minor_status,
            gss_cred_id_t input_cred_handle,
            gss_name_t desired_name,
            gss_OID desired_mech,
            gss_cred_usage_t cred_usage,
            OM_uint32 initiator_time_req,
            OM_uint32 acceptor_time_req,
            gss_const_key_value_set_t cred_store,
            gss_cred_id_t *output_cred_handle,
            gss_OID_set *actual_mechs,
            OM_uint32 *initiator_time_rec,
            OM_uint32 *acceptor_time_rec);

OM_uint32 gss_store_cred_into(
              OM_uint32         *minor_status,
              gss_cred_id_t     input_cred_handle,
              gss_cred_usage_t  cred_usage,
              gss_OID           desired_mech,
              OM_uint32         overwrite_cred,
              OM_uint32         default_cred,
              gss_const_key_value_set_t cred_store,
              gss_OID_set       *elements_stored,
              gss_cred_usage_t  *cred_usage_stored);

Testing

Under tests/gssapi, a test program named t_credstore.c will be added to exercise the new APIs. It will be invoked from t_gssapi.py.

Release notes

Developer experience:

• Add GSSAPI extensions to allow callers to specify credential store locations when acquiring or storing credentials