gss_add_cred Construct credentials incrementally

If both a Table of Contents and Search form are not displayed in separate frames along with this one, you may wish to redisplay this book in a frameset, beginning with the first page.

HP Open Source Security for OpenVMS Volume 3:...

GSSAPI (Generic Security Services Application...

gss_acquire_cred Acquire credential handle

gss_add_oid_set_member Add an object identifier to a set

gss_add_cred -- Construct credentials incrementally

C Prototype

OM_uint32 gss_add_cred(
        OM_uint32         minor_status,
        gss_cred_id_t     input_cred_handle,
        gss_name_t        desired_name,
        gss_OID           desired_mech,
        gss_cred_usage_t  cred_usage,
        OM_uint32         initiator_time_req,
        OM_uint32         acceptor_time_req,
        gss_cred_id_t     output_cred_handle,
        gss_OID_set       actual_mechs,
        OM_uint32         initiator_time_rec,
        OM_uint32         acceptor_time_rec );

Arguments

minor_status
(output) An implementation-specific status code.

input_cred_handle (input) The credential to which a credential-element will be added. If GSS_C_NO_CREDENTIAL is specified, the routine will compose the new credential based on default behavior. (See description). Note that, while the credential handle is not modified by gss_add_cred, the underlying credential will be modified if output_cred_handle is NULL.

desired_name (input) The name of the principal whose credential should be acquired.

desired_mech (input) The underlying security mechanism with which the credential may be used.

cred_usage (input) How the credential may be used. Valid values are as follows:

GSS_C_INITIATE -- Credential will only be used to initiate security contexts.

GSS_C_ACCEPT -- Credential will only be used to accept security contexts.

initiator_time_req (input)
The number of seconds that the credential should remain valid for initiating security contexts. This argument is ignored if the composed credentials are of type GSS_C_ACCEPT. Specify GSS_C_INDEFINITE to request that the credentials have the maximum permitted initiator lifetime.

acceptor_time_req (input) The number of seconds that the credential should remain valid for accepting security contexts. This argument is ignored if the composed credentials are of type GSS_C_INITIATE. Specify GSS_C_INDEFINITE to request that the credentials have the maximum permitted initiator lifetime.

output_cred_handle (output)
The returned credential handle, containing the new credential-element and all the credential-elements from input_cred_handle. If a valid pointer to a gss_cred_id_t is supplied for this argument, gss_add_cred creates a new credential handle containing all credential-elements from the input_cred_handle and the newly acquired credential-element; if NULL is specified for this argument, the newly acquired credential-element will be added to the credential identified by input_cred_handle.

The resources associated with any credential handle returned via this argument must be released by the application after use with a call to gss_release_cred.

actual_mechs (output) The complete set of mechanisms for which the new credential is valid. Storage for the returned OID-set must be freed by the application after use with a call to gss_release_oid_set. Specify NULL if not required.

initiator_time_rec (output)
The actual number of seconds for which the returned credentials will remain valid for initiating contexts using the specified mechanism. If the implementation or mechanism does not support expiration of credentials, the value GSS_C_INDEFINITE will be returned. Specify NULL if not required.

acceptor_time_rec (output)
The actual number of seconds for which the returned credentials will remain valid for accepting security contexts using the specified mechanism. If the implementation or mechanism does not support expiration of credentials, the value GSS_C_INDEFINITE will be returned. Specify NULL if not required.

Description

This routine adds a credential-element to a credential. The credential-element is identified by the name of the principal to which it refers. This routine is not intended to provide a "login to the network" function, as such a function would involve the creation of new mechanism-specific authentication data, rather than merely acquiring a GSSAPI handle to existing data.

If desired_name is GSS_C_NO_NAME, the call is interpreted as a request to add a credential element 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).

This routine is expected to be used primarily by context acceptors, since implementations are likely to provide mechanism-specific ways of obtaining GSSAPI 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.

This routine can be used to either compose a new credential containing all credential-elements of the original in addition to the newly acquired credential element, or to add the new credential-element to an existing credential. If NULL is specified for the output_cred_handle argument, the new credential-element will be added to the credential identified by input_cred_handle; if a valid pointer is specified for the output_cred_handle argument, a new credential handle will be created.

If GSS_C_NO_CREDENTIAL is specified as the input_cred_handle, gss_add_cred will compose a credential (and set the output_cred_handle argument accordingly) based on default behavior. That is, the call will have the same effect as if the application had first made a call to gss_acquire_cred, specifying the same usage and passing GSS_C_NO_NAME as the desired_name argument to obtain an explicit credential handle embodying default behavior, passed this credential handle to gss_add_cred, and finally called gss_release_cred on the first credential handle.

If GSS_C_NO_CREDENTIAL is specified as the input_cred_handle argument, a nonNULL output_cred_handle must be supplied.

Return Values

This routine returns one of the following GSS status codes:

GSS_S_COMPLETE
Successful completion.

GSS_S_BAD_MECH
Unavailable mechanism requested.

GSS_S_BAD_NAMETYPE
The type contained within the desired_name argument is not supported.

GSS_S_BAD_NAME
The value supplied for the desired_name argument is ill formed.

GSS_S_DUPLICATE_ELEMENT
The credential already contains an element for the requested mechanism with overlapping usage and validity period.

GSS_S_CREDENTIALS_EXPIRED
The required credentials could not be added because they have expired.

GSS_S_NO_CRED
No credentials were found for the specified name.

gss_acquire_cred Acquire credential handle

gss_add_oid_set_member Add an object identifier to a set

minor_status (output)		An implementation-specific status code.
input_cred_handle (input)		The credential to which a credential-element will be added. If GSS_C_NO_CREDENTIAL is specified, the routine will compose the new credential based on default behavior. (See description). Note that, while the credential handle is not modified by `gss_add_cred`, the underlying credential will be modified if `output_cred_handle` is NULL.
desired_name (input)		The name of the principal whose credential should be acquired.
desired_mech (input)		The underlying security mechanism with which the credential may be used.
cred_usage (input)		How the credential may be used. Valid values are as follows: GSS_C_INITIATE -- Credential will only be used to initiate security contexts. GSS_C_ACCEPT -- Credential will only be used to accept security contexts.
initiator_time_req (input)
		The number of seconds that the credential should remain valid for initiating security contexts. This argument is ignored if the composed credentials are of type GSS_C_ACCEPT. Specify GSS_C_INDEFINITE to request that the credentials have the maximum permitted initiator lifetime.
acceptor_time_req (input)		The number of seconds that the credential should remain valid for accepting security contexts. This argument is ignored if the composed credentials are of type GSS_C_INITIATE. Specify GSS_C_INDEFINITE to request that the credentials have the maximum permitted initiator lifetime.
output_cred_handle (output)
		The returned credential handle, containing the new credential-element and all the credential-elements from `input_cred_handle`. If a valid pointer to a `gss_cred_id_t` is supplied for this argument, `gss_add_cred` creates a new credential handle containing all credential-elements from the `input_cred_handle` and the newly acquired credential-element; if NULL is specified for this argument, the newly acquired credential-element will be added to the credential identified by `input_cred_handle`. The resources associated with any credential handle returned via this argument must be released by the application after use with a call to `gss_release_cred`.
actual_mechs (output)		The complete set of mechanisms for which the new credential is valid. Storage for the returned OID-set must be freed by the application after use with a call to `gss_release_oid_set`. Specify NULL if not required.
initiator_time_rec (output)
		The actual number of seconds for which the returned credentials will remain valid for initiating contexts using the specified mechanism. If the implementation or mechanism does not support expiration of credentials, the value GSS_C_INDEFINITE will be returned. Specify NULL if not required.
acceptor_time_rec (output)
		The actual number of seconds for which the returned credentials will remain valid for accepting security contexts using the specified mechanism. If the implementation or mechanism does not support expiration of credentials, the value GSS_C_INDEFINITE will be returned. Specify NULL if not required.

GSS_S_COMPLETE	Successful completion.
GSS_S_BAD_MECH	Unavailable mechanism requested.
GSS_S_BAD_NAMETYPE	The type contained within the `desired_name` argument is not supported.
GSS_S_BAD_NAME	The value supplied for the `desired_name` argument is ill formed.
GSS_S_DUPLICATE_ELEMENT	The credential already contains an element for the requested mechanism with overlapping usage and validity period.
GSS_S_CREDENTIALS_EXPIRED	The required credentials could not be added because they have expired.
GSS_S_NO_CRED	No credentials were found for the specified name.