NAME

SYNOPSIS

OM_uint32 gss_acquire_cred(OM_uint32 * minor_status, const gss_name_t desired_name, OM_uint32 time_req, const 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);

ARGUMENTS

OM_uint32 * minor_status

(integer, modify) Mechanism specific status code.

const gss_name_t desired_name

(gss_name_t, read) Name of principal whose credential should be acquired.

OM_uint32 time_req

(Integer, read, optional) Number of seconds that credentials should remain valid. Specify GSS_C_INDEFINITE to request that the credentials have the maximum permitted lifetime.

const gss_OID_set desired_mechs

(Set of Object IDs, read, optional) Set of underlying security mechanisms that may be used. GSS_C_NO_OID_SET may be used to obtain an implementation-specific default.

gss_cred_usage_t cred_usage

(gss_cred_usage_t, read) GSS_C_BOTH - Credentials may be used either to initiate or accept security contexts. GSS_C_INITIATE - Credentials will only be used to initiate security contexts. GSS_C_ACCEPT - Credentials will only be used to accept security contexts.

gss_cred_id_t * output_cred_handle

(gss_cred_id_t, modify) The returned credential handle. Resources associated with this credential handle must be released by the application after use with a call to gss_release_cred().

gss_OID_set * actual_mechs

(Set of Object IDs, modify, optional) The set of mechanisms for which the credential is valid. Storage associated with the returned OID-set must be released by the application after use with a call to gss_release_oid_set(). Specify NULL if not required.

OM_uint32 * time_rec

(Integer, modify, optional) Actual number of seconds for which the returned credentials will remain valid. If the implementation does not support expiration of credentials, the value GSS_C_INDEFINITE will be returned. Specify NULL if not required.

DESCRIPTION

If desired_name is GSS_C_NO_NAME, the call is interpreted as a request for a credential handle that will invoke default behavior when passed to gss_init_sec_context() (if cred_usage is GSS_C_INITIATE or GSS_C_BOTH) or gss_accept_sec_context() (if cred_usage is GSS_C_ACCEPT or GSS_C_BOTH).

Mechanisms should honor the desired_mechs parameter, and return a credential that is suitable to use only with the requested mechanisms. An exception to this is the case where one underlying credential element can be shared by multiple mechanisms; in this case it is permissible for an implementation to indicate all mechanisms with which the credential element may be used. If desired_mechs is an empty set, behavior is undefined.

This routine is expected to be used primarily by context acceptors, since implementations are likely to provide mechanism-specific ways of obtaining GSS-API initiator credentials from the system login process. Some implementations may therefore not support the acquisition of GSS_C_INITIATE or GSS_C_BOTH credentials via gss_acquire_cred for any name other than GSS_C_NO_NAME, or a name produced by applying either gss_inquire_cred to a valid credential, or gss_inquire_context to an active context.

If credential acquisition is time-consuming for a mechanism, the mechanism may choose to delay the actual acquisition until the credential is required (e.g. by gss_init_sec_context or gss_accept_sec_context). Such mechanism-specific implementation decisions should be invisible to the calling application; thus a call of gss_inquire_cred immediately following the call of gss_acquire_cred must return valid credential data, and may therefore incur the overhead of a deferred credential acquisition.

RETURN VALUE

`GSS_S_BAD_MECH`: Unavailable mechanism requested.

`GSS_S_BAD_NAMETYPE`: Type contained within desired_name parameter is not supported.

`GSS_S_BAD_NAME`: Value supplied for desired_name parameter is ill formed.

`GSS_S_CREDENTIALS_EXPIRED`: The credentials could not be acquired Because they have expired.

`GSS_S_NO_CRED`: No credentials were found for the specified name.

REPORTING BUGS

COPYRIGHT

SEE ALSO

info gss

should give you access to the complete manual.