gss_krb5_acquire_cred_cache()--Acquire GSS Credential from a Kerberos Protocol Credentials Cache

 #include <krb5.h>

 krb5_error_code gss_krb5_acquire_cred_cache (
    OM_uint32 *                         minor_status,
    krb5_ccache                         ccache,
    OM_uint32                           time_req,
    gss_cred_usage_t                    cred_usage,
    gss_cred_id_t *                     output_cred_handle,
    OM_uint32 *                         time_rec)

The gss_krb5_acquire_cred_ccache() routine acquires a GSS-API credential using a Kerberos credentials cache. This function allows an application to obtain a GSS-API credential for use with the Kerberos mechanism. The application can then use the credential with the gss_init_sec_context() and gss_accept_sec_context() routines. The Kerberos credentials cache must not be closed until the GSS-API credential is no longer needed and has been deleted.

If GSS_C_INITIATE or GSS_C_BOTH is specified for the credential usage, the application must have a valid ticket in the credentials cache and the ticket must not expire for at least 10 minutes. The gss_krb5_acquire_cred_ccache() routine will use the first valid ticket-granting ticket (or the first valid service ticket if there is no TGT) to create the GSS-API credential.

If GSS_C_ACCEPT or GSS_C_BOTH is specified for the credential usage, the principal associated with the GSS-API credential must be defined in a key table. The KRB5_KTNAME environment variable is used to identify the key table used by the Kerberos security mechanism.

Parameters

minor_status  (Output)

Status code returned from the security mechanism.

ccache  (Input)

The Kerberos credentials cache to be used for the credential. The principal name for the GSS-API credential is obtained from the credentials cache. The credentials cache must contain a valid ticket-granting ticket for this principal if a GSS_C_INITIATE or GSS_C_BOTH credential is Requested.

time_req  (Input)

The number of seconds that the credential remains valid. Specify GSS_C_INDEFINITE to request the maximum credential lifetime. Specify zero for the default lifetime of 2 hours. The actual credential lifetime will be limited by the lifetime of the underlying ticket-granting ticket for GSS_C_INITIATE and GSS_C_BOTH credentials.

cred_usage  (Input)

The desired credential usage as follows:

• GSS_C_INITIATE if the credential can be used only to initiate security contexts.
• GSS_C_ACCEPT if the credential can be used only to accept security contexts.
• GSS_C_BOTH if the credential can be used to both initiate and accept security contexts.

output_cred_handle  (Output)

The handle returned for the GSS-API credential.

time_rec  (Output)

The number of seconds returned for which the credential will remain valid. If the time remaining is not required, specify NULL for this parameter.

Return Value

The return value is one of the following status codes:

GSS_S_COMPLETE

The routine completed successfully.

GSS_S_FAILURE

The routine failed for reasons which are not defined at the GSS level. The minor_status return parameter contains a mechanism-dependent error code describing the reason for the failure.

GSS_S_BAD_MECH

None of the requested mechanisms are supported by the local system.

GSS_S_NO_CRED

The Kerberos credentials cache does not contain a valid ticket-granting ticket.

Authorities

None.

Error Messages

[ Back to top | Security APIs | UNIX-Type APIs | APIs by category ]