gss_acquire_cred(3sec)

Synopsis

#include <dce/gssapi.h>

OM_uint32 gss_acquire_cred (
OM_uint32 *minor_status,
gss_name_t desired_name,
OM_uint32 time_req,
gss_OID_set desired_mechs,
int cred_usage,
gss_cred_id_t *output_cred_handle,
gss_OID_set *actual_mechs,
OM_int32 *time_rec)

Parameters

Input

desired_name
Specifies the principal name to use for the credential.

time_req
Specifies the number of seconds that credentials remain valid.

desired_mechs
Specifies the OID set for the security mechanism to use with the credential, as follows:

To use...	Specify...
DCE Security	GSS_C_NULL_OID_SET
Kerberos	GSSDCE_C_OID_KRBV5_DES
Both DCE Security and Kerberos	GSSDCE_C_OID_DCE_KRBV5_DES and GSSDCE_C_OID_KRBV5_DES

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_ACCEPT	Specifies credentials that the context initiator can use only to accept security contexts.

Output

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.

Description
The gss_acquire_cred( ) routine allows an application to obtain a handle for either an ACCEPT or BOTH credential. The application then passes the credential handle to either the gss_init_sec_context( ) or gss_accept_sec_context( ) routine.

Credential handles created by the gss_acquire_cred( ) routine contain a principal name. If the principal name is unregistered, the gss_acquire_cred( ) routine automatically registers the principal in the default key table. You can change the principal's key table by calling the gssdce_register_acceptor_identify( ) routine.

To create an INITIATE credential, you must use the gssdce_login_context_to_cred( ) routine.

Status Codes
The following describes a partial list of codes (messages) that might be returned. Refer to the OSF DCE Problem Determination Guide for complete descriptions of all messages. 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_FAILURE	The routine failed. See the minor_status parameter return value for more information.

Related Information
Functions:

gss_accept_sec_context(3sec)

gssdce_create_empty_oid_set(3sec)

gssdce_login_context_to_cred(3sec)

gssdce_register_acceptor_identity(3sec)

gss_init_sec_context(3sec)