|
|
gss_acquire_cred(3)
Contents
|
gss_acquire_cred - Acquire credentials for a specific
internal name.
#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 );
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. Description 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 implementation 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 initiate 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
contexts. 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 expiration for acceptors.
A value of GSS_C_INDEFINITE is always
returned for acceptors.
The gss_acquire_cred() function allows an application to
acquire credentials 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 associated 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 Kerberos 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 credentials.
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 [email protected]. 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 [email protected].
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 [email protected].
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.
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
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)
[ Back ] |
