NAME
gss_acquire_cred() — allow an application to acquire a handle for an existing, named credential
SYNOPSIS
#include <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,
int cred_usage,
gss_cred_id_t *output_cred_handle,
gss_OID_set *actual_mechs,
OM_int32 *time_rec );
DESCRIPTION
The
gss_acquire_cred()
routine allows an application to obtain a
handle for a pre-existing credential by name. The credentials could be
either an ACCEPT, INITIATE, or BOTH.
The application then passes the credential handle to either the
gss_init_sec_context()
or the
gss_accept_sec_context()
routine.
If
desired_name
is
GSS_C_NO_NAME,
the call is interpreted as a
request for a credential handle that will invoke default behavior.
Input Parameters
- desired_name
Specifies the principal name to use for the credential.
- time_req
Number of seconds that credentials remain valid. Specify
GSS_C_INDEFINITE
to request that the credentials have
the maximum permitted lifetime.
- desired_mechs
Specifies the OID set for the security mechanism to use with the credential.
To help ensure portability of your application, request the default security
mechanism by specifying
GSS_C_NULL_OID_SET.
- cred_usage
Specify one of the following:
- GSS_C_BOTH
Specifies credentials that the context initiator can use to either
initiate or accept security contexts.
- GSS_C_INITIATE
Specifies credentials that the context initiator can use only to initiate
security contexts.
- GSS_C_ACCEPT
Specifies credentials that the context initiator can use only to accept
security contexts.
Output Parameters
- output_cred_handle
Returns the handle for the return credential.
- actual_mechs
Returns a set of mechanisms for which the credential is valid.
This information is optional. If you do not want a set of mechanisms
returned, specify NULL.
- time_rec
Returns the actual number of seconds for which the return credential
remains valid. This information is optional. If the actual number of
seconds is not required, specify NULL.
- minor_status
Returns a status code from the security mechanism.
STATUS CODES
The following list explains the GSS status codes that can be returned:
- GSS_S_COMPLETE
The routine was completed successfully.
- GSS_S_BAD_MECH
The requested security mechanism is unsupported or unavailable.
- GSS_S_BAD_NAMETYPE
The name passed by the
desired_name
parameter is unsupported.
- GSS_S_BAD_NAME
An invalid name was passed by the
desired_name
parameter.
- 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 routine failed. See the
minor_status
parameter return value
for more information.
AUTHOR
gss_acquire_cred()
was developed by Sun Microsystems, Inc.
SEE ALSO
gss_init_sec_context(3).
The manpages for DCE-GSSAPI are included with the DCE-CoreTools product.
To see those manpages add
/opt/dce/share/man
to
MANPATH.