The gss_add_cred() function 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 as a function to login to the network; a function for login to the network would involve creating new mechanism-specific authentication data rather than merely acquiring a handle to existing data.

If the value of 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(3GSS) (if the value of cred_usage is GSS_C_INITIATE or GSS_C_BOTH) or gss_accept_sec_context(3GSS) (if the value of cred_usage is GSS_C_ACCEPT or GSS_C_BOTH).

The gss_add_cred() function is expected to be used primarily by context acceptors, since the GSS-API provides mechanism-specific ways to obtain GSS-API initiator credentials through the system login process. Consequently, the GSS-API therefore does not support acquiring GSS_C_INITIATE or GSS_C_BOTH credentials by means of gss_acquire_cred(3GSS) for any name other than GSS_C_NO_NAME, or from name produced by gss_inquire_cred(3GSS) applied to a valid credential or gss_inquire_context(3GSS) applied 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, for example, by gss_init_sec_context(3GSS) or by gss_accept_sec_context(3GSS). Such mechanism-specific implementation decisions are, however, invisible to the calling application; thus a call to gss_inquire_cred(3GSS) immediately following the call of gss_add_cred() will return valid credential data as well as incur the overhead of deferred credential acquisition.

The gss_add_cred() routine can be used either to compose a new credential that contains 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 the value of the output_cred_handle parameter argument is NULL, 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 parameter, a new credential handle will be created.

If the value of input_cred_handle is GSS_C_NO_CREDENTIAL, gss_add_cred() will compose a credential and set the output_cred_handle parameter based on the default behavior. That is, the call will have the same effect as if the application had first made a call to gss_acquire_cred(3GSS) specifying the same usage and passing GSS_C_NO_NAME as the desired_name parameter to obtain an explicit credential handle that incorporates the default behaviors, then passed this credential handle to gss_add_cred(), and finally called gss_release_cred(3GSS) on the first credential handle.

If the value of the input_cred_handle parameter is GSS_C_NO_CREDENTIAL, you must supply a non-NULL value for the output_cred_handle parameter.

The parameter descriptions for gss_acquire_cred() follow:

minor_status

A mechanism specific status code.

input_cred_handle

The credential to which the credential-element will be added. If GSS_C_NO_CREDENTIAL is specified, the routine will compose the new credential based on default behavior. While the credential-handle is not modified by gss_add_cred(), if output_credential_handle is NULL, the underlying credential will be modified.

desired_name

Name of principal for which a credential should be acquired.

desired_mech

If the value of desired_mech is GSS_C_BOTH, the credential may be used either to initiate or accept security contexts. If the value of desired_mech is GSS_C_INITIATE, the credential will only be used to initiate security contexts. The credential will only be used to accept security contexts, if the value of desired_mech is GSS_C_ACCEPT.

initiator_time_req

The number of seconds that the credential may 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

Number of seconds that the credential may 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

The returned credential handle that contains 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 parameter, gss_add_cred() creates a new credential handle containing all credential-elements from input_cred_handle and the newly acquired credential-element; if NULL is specified for this parameter, the newly acquired credential-element will be added to the credential identified by input_cred_handle.

The resources associated with any credential handle returned by means of this parameter must be released by the application after use by a call to gss_release_cred(3GSS).

actual_mechs

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 by a call to gss_release_oid_set(3GSS). Specify NULL if this parameter is not required.

initiator_time_rec

The actual number of seconds for which the returned credentials will remain valid for initiating contexts using the specified mechanism. If a mechanism does not support expiration of credentials, the value GSS_C_INDEFINITE will be returned. Specify NULL if this parameter is not required

acceptor_time_rec

The actual number of seconds for which the returned credentials will remain valid for accepting security contexts using the specified mechanism. If a mechanism does not support expiration of credentials, the value GSS_C_INDEFINITE will be returned. Specify NULL if this parameter is not required.

gss_acquire_cred() may return the following status codes:

GSS_S_COMPLETE

Successful completion.

GSS_S_BAD_MECH

An unavailable mechanism has been requested.

GSS_S_BAD_NAMETYPE

The type contained within the desired_name parameter is not supported.

GSS_S_BAD_NAME

The value supplied for desired_name parameter is ill formed.

GSS_S_DUPLICATE_ELEMENT

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

GSS_S_CREDENTIALS_EXPIRED

The credentials could not be added because they have expired.

GSS_S_NO_CRED

No credentials were found for the specified name.

GSS_S_FAILURE

The underlying mechanism detected an error for which no specific GSS status code is defined. The mechanism-specific status code reported by means of the minor_status parameter details the error condition.

See attributes(5) for descriptions of the following attributes:

gss_accept_sec_context(3GSS), gss_acquire_cred(3GSS), gss_init_sec_context(3GSS), gss_inquire_context(3GSS)gss_inquire_cred(3GSS), gss_release_cred(3GSS), gss_release_oid_set(3GSS), attributes(5)

GSS-API Programming Guide