NAME | SYNOPSIS | DESCRIPTION | PARAMETERS | ERRORS | ATTRIBUTES | SEE ALSO
cc -flag … file …-lgss [library …] #include <gssapi/gssapi.h>OM_uint32 gss_add_cred(OM_uint32 *minor_status, const gss_cred_id_t input_cred_handle, const gss_name_t desired_name, const 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);
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:
A mechanism specific status code.
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.
Name of principal for which a credential should be acquired.
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.
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.
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.
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).
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.
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
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:
Successful completion.
An unavailable mechanism has been requested.
The type contained within the desired_name parameter is not supported.
The value supplied for desired_name parameter is ill formed.
The credential already contains an element for the requested mechanism that has overlapping usage and validity period.
The credentials could not be added because they have expired.
No credentials were found for the specified name.
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:
ATTRIBUTE TYPE |
ATTRIBUTE VALUE |
---|---|
Availability |
SUNWgss (32–bit) |
|
SUNWgssx (64–bit) |
MT-Level |
Safe |
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)
NAME | SYNOPSIS | DESCRIPTION | PARAMETERS | ERRORS | ATTRIBUTES | SEE ALSO