GSS_ACQUIRE_CRED(3GSS)GSS_ACQUIRE_CRED(3GSS)NAMEgss_acquire_cred - acquire a handle for a pre-existing credential by
cc [ flag... ] file... -lgss [ library... ]
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,
The gss_acquire_cred() function allows an application to acquire a han‐
dle 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 net‐
work would involve creating new credentials rather than merely acquir‐
ing 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
gss_acquire_cred() is intended to be used primarily by context accep‐
tors, since the GSS-API routines obtain initiator credentials through
the system login process. Accordingly, you may not acquire GSS_C_INITI‐
ATE 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 mecha‐
nism 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.
The parameter descriptions for gss_acquire_cred() follow:
The name of the principal for which a credential
should be acquired.
The number of seconds that credentials remain
valid. Specify GSS_C_INDEFINITE to request that
the credentials have the maximum permitted life‐
The set of underlying security mechanisms that
may be used. GSS_C_NO_OID_SET may be used to
obtain a default.
A flag that indicates how this credential should
be used. If the flag is GSS_C_ACCEPT, then cre‐
dentials will be used only to accept security
credentials. GSS_C_INITIATE indicates that cre‐
dentials will be used only to initiate security
credentials. If the flag is GSS_C_BOTH, then cre‐
dentials may be used either to initiate or accept
The returned credential handle. Resources asso‐
ciated with this credential handle must be
released by the application after use with a call
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). Spec‐
ify NULL if not required.
Actual number of seconds for which the returned
credentials will remain valid. Specify NULL if
Mechanism specific status code.
ERRORSgss_acquire_cred() may return the following status code:
An unavailable mechanism has been
The type contained within the desired_name
parameter is not supported.
The value supplied for desired_name param‐
eter is ill formed.
The credentials could not be acquired
because they have expired.
No credentials were found for the speci‐
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.
See attributes(5) for descriptions of the following attributes:
│ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
│MT-Level │ Safe │
SEE ALSOgss_accept_sec_context(3GSS), gss_init_sec_context(3GSS),
gss_release_cred(3GSS), gss_release_oid_set(3GSS), attributes(5)
Solaris Security for Developers Guide
Jan 14, 2003 GSS_ACQUIRE_CRED(3GSS)