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
- 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.
- 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 ]