Tribblix: manual page: gss_acquire

GSS_ACQUIRE_CRED(3GSS) Generic Security Services API Library Functions

NAME

gss_acquire_cred - acquire a handle for a pre-existing credential by
name

SYNOPSIS

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

OM_uint32 gss_acquire_cred(OM_uint32 *minor_status,
const gss_name_t *desired_name, OM_uint32 time_req,
const gss_OID_set desired_mech, gss_cred_usage_t cred_usage,
gss_cred_id_t * output_cred_handle, gss_OID_set *actual_mechs,
OM_uint32 *time_rec);

DESCRIPTION

The gss_acquire_cred() function allows an application to acquire a
handle for a pre-existing credential by name. This routine is not
intended as a function to login to the network; a function for login
to the network would involve creating new credentials rather than
merely acquiring a handle to existing credentials.

If desired_name is GSS_C_NO_NAME, the call is interpreted as a
request for a credential handle that will invoke default behavior
when passed to gss_init_sec_context(3GSS) (if cred_usage is
GSS_C_INITIATE or GSS_C_BOTH) or gss_accept_sec_context(3GSS) (if
cred_usage is GSS_C_ACCEPT or GSS_C_BOTH).

Normally gss_acquire_cred() returns a credential that is valid only
for the mechanisms requested by the desired_mechs argument. However,
if multiple mechanisms can share a single credential element, the
function returns all the mechanisms for which the credential is valid
in the actual_mechs argument.

gss_acquire_cred() is intended to be used primarily by context
acceptors, since the GSS-API routines obtain initiator credentials
through the system login process. Accordingly, you may not acquire
GSS_C_INITIATE or GSS_C_BOTH credentials by means of
gss_acquire_cred() for any name other than GSS_C_NO_NAME.
Alternatively, you may acquire GSS_C_INITIATE or GSS_C_BOTH
credentials for a name produced when gss_inquire_cred(3GSS) is
applied to a valid credential, or when gss_inquire_context(3GSS) is
applied to an active context.

If credential acquisition is time-consuming for a mechanism, the
mechanism may choose to delay the actual acquisition until the
credential is required, for example, by gss_init_sec_context(3GSS) or
by gss_accept_sec_context(3GSS). Such mechanism-specific
implementations are, however, invisible to the calling application;
thus a call of gss_inquire_cred(3GSS) immediately following the call
of gss_acquire_cred() will return valid credential data and incur the
overhead of a deferred credential acquisition.

PARAMETERS

The parameter descriptions for gss_acquire_cred() follow:

desired_name
The name of the principal for which a
credential should be acquired.

time_req
The number of seconds that credentials remain
valid. Specify GSS_C_INDEFINITE to request
that the credentials have the maximum permitted
lifetime

desired_mechs
The set of underlying security mechanisms that
may be used. GSS_C_NO_OID_SET may be used to
obtain a default.

cred_usage
A flag that indicates how this credential
should be used. If the flag is GSS_C_ACCEPT,
then credentials will be used only to accept
security credentials. GSS_C_INITIATE indicates
that credentials will be used only to initiate
security credentials. If the flag is
GSS_C_BOTH, then credentials may be used either
to initiate or accept security contexts.

output_cred_handle
The returned credential handle. Resources
associated with this credential handle must be
released by the application after use with a
call to gss_release_cred(3GSS)

actual_mechs
The set of mechanisms for which the credential
is valid. Storage associated with the returned
OID-set must be released by the application
after use with a call to
gss_release_oid_set(3GSS). Specify NULL if not
required.

time_rec
Actual number of seconds for which the returned
credentials will remain valid. Specify NULL if
not required.

minor_status
Mechanism specific status code.

ERRORS

gss_acquire_cred() may return the following status code:

GSS_S_COMPLETE
Successful completion.

GSS_S_BAD_MECH
An unavailable mechanism has been
requested.

GSS_S_BAD_NAMETYPE
The type contained within the
desired_name parameter is not supported.

GSS_S_BAD_NAME
The value supplied for desired_name
parameter is ill formed.

GSS_S_CREDENTIALS_EXPIRED
The credentials could not be acquired
because they have expired.

GSS_S_NO_CRED
No credentials were found for the
specified name.

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.