NAME

gss_acquire_cred — Allows an application to acquire a handle for an existing named credential

Synopsis

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_reqSpecifies the number of seconds that credentials remain valid. 

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

DCE security
Specify GSS_C_NULL_OID_SET. 

KerberosSpecify GSSDCE_C_OID_KRBV5_DES. 

Both DCE security and Kerberos
Specify 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_usageSpecify 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_recReturns 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 a BOTH credential.  The application then passes the credential handle to either the gss_init_sec_context() routine or the 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 status codes 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: gssdce_accept_sec_context(3sec), gssdce_create_empty_oid_set(3sec), gssdce_login_context_to_credential(3sec), gssdce_register_acceptor_identity(3sec), gss_init_sec_context(3sec).