gss_acquire_cred()--Acquire GSS Credential


  Syntax 
 #include <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,
     gss_cred_usage_t   cred_usage,
     gss_cred_id_t *    output_cred_handle,  
     gss_OID_set *    actual_mechs,
     OM_uint32 *    time_rec);
  Service Program Name: QSYS/QKRBGSS

  Default public authority: *USE

  Threadsafe: Yes

The gss_acquire_cred() function allows an application to acquire a GSS credential. The application can then use the credential with the gss_init_sec_context() and gss_accept_sec_context() routines.


Parameters

minor_status  (Output)
A status code from the security mechanism.

desired_name  (Input)
The principal name to be used for the credential. Specify GSS_C_NO_NAME for this parameter to use the name obtained from the default login context.

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 is limited by the lifetime of the underlying ticket-granting ticket for GSS_C_INITIATE and GSS_C_BOTH credentials.

desired_mechs  (Input)
The desired security mechanisms for use with the credential. Mechanisms that are not available on the local system are ignored. The actual mechanisms that can be used with the credential are returned in the actual_mechs parameter. Specify GSS_C_NO_OID_SET for this parameter to use the default mechanism of gss_mech_krb5.

The following security mechanisms are supported:

gss_mech_krb5_old Beta Kerberos V5 mechanism
gss_mech_krb5 Kerberos V5 mechanism


cred_usage  (Input)
The desired credential usage as follows:

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


output_cred_handle  (Output)
The handle for the GSS credential.

actual_mechs  (Output)
The set of mechanism identifiers for which the credential is valid. If the actual mechanisms are not required, specify NULL for this parameter. The gss_OID_set returned for this parameter should be released by calling the gss_release_oid_set() routine when it is no longer needed.

time_rec  (Output)
The number of seconds 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_BAD_MECH
None of the requested mechanisms are supported by the local system.

GSS_S_BAD_NAME
The name specified for the desired_name parameter is not valid.

GSS_S_BAD_NAMETYPE
The name specified for the desired_name parameter is not supported by the applicable underlying GSS mechanisms.

GSS_S_COMPLETE
The routine completed successfully.

GSS_S_FAILURE
The routine failed for reasons that 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_NO_CRED
No credentials are available or the credentials are valid for context initiation use only.

Authorities

Object Referred to Data Authority Required
Each directory in the path name preceding the configuration file *X
Configuration file *R
Each directory preceding the credential cache file if GSS_C_INITIATE or GSS_C_BOTH is specified for credential usage *X
Credential cache file *RW
Each directory preceding the keytab file if GSS_C_ACCEPT or GSS_C_BOTH is specified for credential usage *X
Keytab file *R


Error Messages

Message ID Error Message Text
CPE3418 E Possible APAR condition or hardware failure.


Usage Notes

  1. If GSS_C_INITIATE or GSS_C_BOTH is specified for the credential usage, the application must have a valid ticket-granting ticket in the default credentials cache and the ticket must not expire for at least 10 minutes. The gss_acquire_cred() routine uses this ticket-granting ticket to create the GSS credential. The principal specified by the desired_name parameter must match the principal obtained from the credentials cache or must be specified as GSS_C_NO_NAME. The KRB5CCNAME environment variable is used to identify the credentials cache used by the Kerberos security mechanism.

  2. If GSS_C_ACCEPT or GSS_C_BOTH is specified for the credential usage, the principal specified by the desired_name parameter must be defined in a key table. The KRB5_KTNAME environment variable can be used to set the key table used by the Kerberos security mechanism.

API introduced: V5R1

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