NAME

gss_add_cred − Obtain credentials that allow a user to accept security contexts. 

SYNOPSIS

#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_mech,
        OM_uint32 ∗ initiator_time_rec,
        OM_uint32 ∗ acceptor_time_rec );

PARAMETERS

minor_status
Kerberos 5 error code.

input_cred_handle
The credential to which a credential element is added. If GSS_C_NO_CREDENTIAL is specified, the function creates a new credential based on default behavior.  In this case, a non-NULL output_cred_handle must be supplied. 

desired_name
Name of the principal whose credentials are to be acquired. The internal form name must be obtained beforehand using a call such as gss_import_name(). 

If GSS_C_NO_NAME is specified, the call is interpreted as a request for the credentials of the default principal.  gss_acquire_cred() explains how Kerberos 5 handles default principals. Note that only acceptor credentials may be obtained with the HP Application Security SDK implementation of gss_add_cred(). 

desired_mech
Object identifier (OID) set of security mechanisms that can be used to acquire user credentials. Specify rfc_krb5_c_OID to select Kerberos 5 that is supported by the HP implementation of the GSS-API. 

cred_usage
Type of credentials to acquire. Typically, clients initiate and servers accept. Credentials of type GSS_C_BOTH are used by servers that also act as clients by contacting other servers. 

GSS_C_BOTH
Not supported by the HP Application Security SDK

GSS_C_INITIATE
Not supported by the HP Application Security SDK.

GSS_C_ACCEPT
Credentials may be used only to accept security contexts.

initiator_time_req
Number of seconds that the credential should remain valid for initiating security contexts. This parameter is ignored by the HP Application Security SDK because it does not support initiator credentials with this function.

acceptor_time_req
Number of seconds that the credential should remain valid for accepting security contexts. This parameter is ignored because the HP implementation of the GSS-API does not support credentials expiration for accepting applications.

output_cred_handle
The returned credentials, containing the new credential element and all the credential elements from input_cred_handle, if a valid pointer was supplied. If NULL is specified for this parameter, the newly acquired credentials element is added to the credentials identified by input_cred_handle. Do not specify NULL for this parameter if a NULL value was specified for input_cred_handle. 

The resources associated with the returned credentials must be released by the application after use with a call to gss_release_cred(). 

actual_mechs
Security mechanisms for which the credentials are valid. Application Security SDK supports Kerberos 5. Specify NULL if this information is not required. 

The storage associated with the returned OID set must be released by the application after use with a call to gss_release_oid_set(). 

initiator_time_rec
Actual number of seconds for which the returned credentials remain valid for initiating contexts using the specified mechanism. Specify NULL if this information is not required. 

This parameter is ignored by the HP Application Security SDK because it does not support initiator credentials with this function. 

acceptor_time_rec
Actual number of seconds for which the returned credentials remain valid for accepting security contexts using the specified mechanism. Specify NULL if this information is not required. 

Since the HP implementation of the GSS-API does not support expiration of acceptor credentials, the value GSS_C_INDEFINITE is always returned. 

DESCRIPTION

The gss_add_cred() function allows an application to construct credentials iteratively by adding credential elements for different security mechanisms. It can be used to:

       •Create new credentials containing all credential elements of the original in addition to a newly-acquired credential element. 

       •Add a new credential element to existing credentials. 

If NULL is specified for the output_cred_handle parameter argument, the new credential element is added to the credentials identified by input_cred_handle. If a valid pointer is specified for the output_cred_handle parameter, new credentials are created. 

The resulting credentials allow a principal to accept security contexts.  The HP implementation of this function does not support initiator credentials. 

Before calling this function, the application should call a function such as gss_import_name() to obtain the internal name of the principal. Otherwise, the default principal is used. 

To avoid memory leaks, the application must release the resources associated with the credentials with a call to gss_release_cred() after it is finished establishing security contexts. The storage associated with mechanisms OID set can be released anytime with a call to gss_release_oid_set(). 

If a principal name is not specified with this function, default Kerberos 5 behavior is invoked.  gss_acquire_cred() explains default principals. 

RETURN VALUES

PORTABILITY CONSIDERATIONS

The HP implementation of the GSS-API supports only acceptor credentials for this function. Usage types GSS_C_INITIATE and GSS_C_BOTH may not be specified. 

SEE ALSO

Functions:  gss_acquire_cred(3), gss_import_name(3), gss_release_cred(3), gss_release_oid_set(3)