Tribblix: manual page: gss_store

GSS_STORE_CRED(3GSS) Generic Security Services API Library Functions

NAME

gss_store_cred - store a credential in the current credential store

SYNOPSIS

cc [ flag... ] file... -lgss [ library... ]
#include <gssapi/gssapi.h>

OM_uint32 gss_store_cred(OM_uint32 *minor_status,
const gss_cred_id_t input_cred, const 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);

PARAMETERS

The parameter descriptions for gss_store_cred() follow:

input_cred
The credential to be stored.

cred_usage
This parameter specifies whether to store an
initiator, an acceptor, or both usage components
of a credential.

desired_mech
The mechanism-specific component of a credential
to be stored. If GSS_C_NULL_OID is specified,
the gss_store_cred() function attempts to store
all the elements of the given input_cred_handle.

The gss_store_cred() function is not atomic when
storing multiple elements of a credential. All
delegated credentials, however, contain a single
element.

overwrite_cred
A boolean that indicates whether to overwrite
existing credentials in the current store for
the same principal as that of the
input_cred_handle. A non-zero value indicates
that credentials are overwritten. A zero value
indicates that credentials are not overwritten.

default_cred
A boolean that indicates whether to set the
principal name of the input_cred_handle
parameter as the default of the current
credential store. A non-zero value indicates
that the principal name is set as the default. A
zero value indicates that the principal name is
not set as the default. The default principal of
a credential store matches GSS_C_NO_NAME as the
desired_name input parameter for
gss_store_cred(3GSS).

elements_stored
The set of mechanism OIDs for which
input_cred_handle elements have been stored.

cred_usage_stored
The stored input_cred_handle usage elements:
initiator, acceptor, or both.

minor_status
Minor status code that is specific to one of the
following: the mechanism identified by the
desired_mech_element parameter, or the element
of a single mechanism in the input_cred_handle.
In all other cases, minor_status has an
undefined value on return.

DESCRIPTION

The gss_store_cred() function stores a credential in the current GSS-
API credential store for the calling process. Input credentials can
be re-acquired through gss_add_cred(3GSS) and gss_acquire_cred(3GSS).

The gss_store_cred() function is specifically intended to make
delegated credentials available to a user's login session.

The gss_accept_sec_context() function can return a delegated GSS-API
credential to its caller. The function does not store delegated
credentials to be acquired through gss_add_cred(3GSS). Delegated
credentials can be used only by a receiving process unless they are
made available for acquisition by calling the gss_store_cred()
function.

The Solaris Operating System supports a single GSS-API credential
store per user. The current GSS-API credential store of a process is
determined by its effective UID.

In general, acceptor applications should switch the current
credential store by changing the effective UID before storing a
delegated credential.

RETURN VALUES

The gss_store_cred() can return the following status codes:

GSS_S_COMPLETE

Successful completion.

GSS_S_CREDENTIALS_EXPIRED

The credentials could not be stored because they have expired.

GSS_S_CALL_INACCESSIBLE_READ

No input credentials were given.

GSS_S_UNAVAILABLE

The credential store is unavailable.

GSS_S_DUPLICATE_ELEMENT

The credentials could not be stored because the overwrite_cred
input parameter was set to false (0) and the input_cred parameter
conflicts with a credential in the current credential store.

GSS_S_FAILURE

The underlying mechanism detected an error for which no specific
GSS status code is defined. The mechanism-specific status code
reported by means of the minor_status parameter details the error
condition.