HP Open Source Security for OpenVMS Volume 3: Kerberos > Chapter 5 GSSAPI (Generic Security Services Application Programming Interface)

gss_add_cred — Construct credentials incrementally

 » Table of Contents

 » Glossary

 » Index

spacerspacerspacer
spacer
spacer
  		 
 

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_MECHUnavailable mechanism requested.
GSS_S_BAD_NAMETYPEThe type contained within the desired_name argument is not supported.
GSS_S_BAD_NAMEThe 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