(gss_name_t, read) Name of principal whose
credential should be acquired.
OM_uint32 time_req
(Integer, read, optional) Number of seconds that
credentials should remain valid. Specify GSS_C_INDEFINITE to
request that the credentials have the maximum permitted lifetime.
const gss_OID_set desired_mechs
(Set of Object IDs, read, optional) Set of
underlying security mechanisms that may be used.
GSS_C_NO_OID_SET may be used to obtain an implementation-specific
default.
gss_cred_usage_t cred_usage
(gss_cred_usage_t, read) GSS_C_BOTH - Credentials may
be used either to initiate or accept security contexts.
GSS_C_INITIATE - Credentials will only be used to initiate
security contexts. GSS_C_ACCEPT - Credentials will only be used
to accept security contexts.
gss_cred_id_t * output_cred_handle
(gss_cred_id_t, modify) 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().
gss_OID_set * actual_mechs
(Set of Object IDs, modify, optional) 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(). Specify NULL if
not required.
OM_uint32 * time_rec
(Integer, modify, optional) Actual number of seconds for
which the returned credentials will remain valid. If the
implementation does not support expiration of credentials, the
value GSS_C_INDEFINITE will be returned. Specify NULL if not
required.
DESCRIPTION
Allows an application to acquire a handle for a pre-existing
credential by name. GSS-API implementations must impose a local
access-control policy on callers of this routine to prevent
unauthorized callers from acquiring credentials to which they are
not entitled. This routine is not intended to provide a "login to
the network" function, as such a function would involve the
creation of new credentials rather than merely acquiring a handle
to existing credentials. Such functions, if required, should be
defined in implementation-specific extensions to the API.
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() (if cred_usage is
GSS_C_INITIATE or GSS_C_BOTH) or gss_accept_sec_context() (if
cred_usage is GSS_C_ACCEPT or GSS_C_BOTH).
Mechanisms should honor the desired_mechs parameter, and return a
credential that is suitable to use only with the requested
mechanisms. An exception to this is the case where one underlying
credential element can be shared by multiple mechanisms; in this
case it is permissible for an implementation to indicate all
mechanisms with which the credential element may be used. If
desired_mechs is an empty set, behavior is undefined.
This routine is expected to be used primarily by context acceptors,
since implementations are likely to provide mechanism-specific ways
of obtaining GSS-API initiator credentials from the system login
process. Some implementations may therefore not support the
acquisition of GSS_C_INITIATE or GSS_C_BOTH credentials via
gss_acquire_cred for any name other than GSS_C_NO_NAME, or a name
produced by applying either gss_inquire_cred to a valid credential,
or gss_inquire_context 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 (e.g. by gss_init_sec_context or
gss_accept_sec_context). Such mechanism-specific implementation
decisions should be invisible to the calling application; thus a
call of gss_inquire_cred immediately following the call of
gss_acquire_cred must return valid credential data, and may
therefore incur the overhead of a deferred credential acquisition.