gss_acquire_cred(3)gss_acquire_cred(3)NAMEgss_acquire_cred - Acquire credentials for a specific internal name.
SYNOPSIS
#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_mechs,
gss_cred_usage_t cred_usage,
gss_cred_id_t * output_cred_handle,
gss_OID_set * actual_mechs,
OM_uint32 * time_rec );
PARAMETERS
Kerberos 5 error code. Name of the principal whose credentials are to
be acquired. The internal form name must be obtained beforehand using a
call such as gss_import_name().
If GSS_C_NO_NAME is specified, the call is interpreted as a
request for the credentials of the default principal. Descrip‐
tion contains an explanation of how Kerberos 5 handles default
principals. Requested number of seconds that credentials remain
valid. This parameter is ignored by the HP implementation of the
GSS-API because it extracts from the credentials cache based on
principal identity, not longevity. Credentials lifetime is
determined external to GSS when the credentials are copied into
the cache. Object identifier (OID) set of security mechanisms
that can be used to acquire user credentials. The HP implemen‐
tation of the GSS-API supports Kerberos 5.
Specify either rfc_krb5_c_OID_set for Kerberos 5 or
GSS_C_NO_OID_SET to obtain the default mechanism set that is the
same. Type of credentials to acquire. Typically, clients initi‐
ate and servers accept. Credentials of type GSS_C_BOTH are used
by servers that also act as clients by contacting other servers.
Credentials may be used to either initiate or accept security
contexts. Credentials may be used only to initiate security
contexts. Credentials may be used only to accept security con‐
texts. The credentials that are returned for the principal
name.
The resources associated with these credentials must be released
by the application after use with a call to gss_release_cred().
Security mechanisms for which the credentials are valid.
The storage associated with the returned OID set must be
released by the application after use with a call to
gss_release_oid_set(). Actual number of seconds the returned
credentials remain valid.
This parameter is valid only for initiator credentials. The HP
implementation of the GSS-API does not support credentials expi‐
ration for acceptors. A value of GSS_C_INDEFINITE is always
returned for acceptors.
DESCRIPTION
The gss_acquire_cred() function allows an application to acquire cre‐
dentials by principal name. The credentials must already exist in a
credentials cache created by a kinit command, HP Credentials Manager,
or a csf_gss_acq_user() function call. The resulting credentials allow
a principal to initiate and/or accept security contexts (depending on
the type of credential).
Before calling this function, the application should call a function
such as gss_import_name() to obtain the internal name of the principal.
Otherwise, the default principal is used.
To avoid memory leaks, the application must release the resources asso‐
ciated with the credentials with a call to gss_release_cred() after it
is finished establishing security contexts. The storage associated with
mechanisms OID set can be released anytime with a call to
gss_release_oid_set().
When a principal name is specified with gss_acquire_cred(), it is used
to search the credentials cache for credentials. If valid credentials
are not found, the service key table is searched. If no credentials are
found, the gss_acquire_cred() function returns GSS_S_NO_CRED.
If a principal name is not specified with this function, default Ker‐
beros 5 behavior is invoked: For cred_usage of GSS_S_INITIATE and a
desired_name of GSS_C_NO_NAME: The credentials cache or the service key
table are searched for a default principal. If a default is found, it
is then used to search the credentials cache and service key table for
initiator credentials. If a default principal name is not found, the
user login name is used to search the service key table for creden‐
tials.
For example, assume that user John Q. Public has the login ID of
john and that his UNIX uid is 112 and his realm is COMPANY.COM.
The name of John's default credentials cache would be derived
from his UNIX uid as /krb5/tmp/cc/krb5cc_112. Assuming John did
not specify an alternate principal when he executed the kinit
command or when the csf_gss_acq_user() function was called, the
cache's default principal would be john@COMPANY.COM. Therefore,
when John executes an application that calls gss_acquire_cred(),
setting cred_usage as GSS_C_INITIATE and desired_name as
GSS_C_NO_NAME, the principal name used is john@COMPANY.COM.
If there is no cache, the default name and realm are still used.
Assuming COMPANY.COM is the default realm, the principal name
used is john@COMPANY.COM. For cred_usage of GSS_S_ACCEPT or
GSS_C_BOTH and a desired_name of GSS_C_NO_NAME: The principal
name is formed from default values. The resulting form uses
host/FQDN@REALM, where FQDN is the host's fully qualified domain
name and REALM is the host's default realm. The credentials
cache and service key table are then searched for credentials.
A common error that occurs when acquiring credentials of usage
GSS_S_ACCEPT or GSS_C_BOTH is that the service key table file is
not readable by the application.
This function is optional if default credentials are used. For
example, if an initiating application does not call
gss_acquire_cred() before a gss_init_sec_context() call is made,
credentials with the default name and usage GSS_C_INITIATE are
acquired. Similarly, if an accepting application does not call
gss_acquire_cred() before a gss_accept_sec_context() call is
made, credentials with the default name and usage GSS_C_ACCEPT
are acquired.
RETURN VALUES
GSS_S_BAD_MECH xx01xxxx
GSS_S_BAD_NAME xx02xxxx
GSS_S_BAD_NAMETYPE xx03xxxx
GSS_S_CALL_BAD_STRUCTURE 03xxxxxx
GSS_S_CALL_INACCESSIBLE_READ 01xxxxxx
GSS_S_CALL_INACCESSIBLE_WRITE 02xxxxxx
GSS_S_COMPLETE 00000000
GSS_S_FAILURE xx0Dxxxx
GSS_S_NO_CRED xx07xxxx
SEE ALSO
Functions: csf_gss_acq_user(3), gss_accept_sec_context(3),
gss_add_cred(3), gss_import_name(3), gss_init_sec_context(3),
gss_inquire_cred(3), gss_inquire_cred_by_mech(3), gss_release_cred(3),
gss_release_oid_set(3)gss_acquire_cred(3)