gss_add_cred(3)gss_add_cred(3)NAMEgss_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
Kerberos 5 error code. 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 out‐
put_cred_handle must be supplied. Name of the principal whose creden‐
tials 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 prin‐
cipals. Note that only acceptor credentials may be obtained with
the HP Application Security SDK implementation of
gss_add_cred(). Object identifier (OID) set of security mecha‐
nisms 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. 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. Not supported by the HP Application
Security SDK Not supported by the HP Application Security SDK.
Credentials may be used only to accept security contexts. Num‐
ber of seconds that the credential should remain valid for ini‐
tiating security contexts. This parameter is ignored by the HP
Application Security SDK because it does not support initiator
credentials with this function. Number of seconds that the cre‐
dential 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. The returned credentials, containing the new cre‐
dential 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(). Security mechanisms for which the creden‐
tials 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(). 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. Actual number of seconds for which the returned cre‐
dentials 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 creden‐
tials 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 creden‐
tials.
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 out‐
put_cred_handle parameter, new credentials are created.
The resulting credentials allow a principal to accept security con‐
texts. The HP implementation of this function does not support initia‐
tor 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 asso‐
ciated 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 Ker‐
beros 5 behavior is invoked. gss_acquire_cred() explains default prin‐
cipals.
RETURN VALUES
GSS_S_BAD_MECH xx01xxxx
GSS_S_BAD_NAME xx02xxxx
GSS_S_BAD_NAMETYPE xx03xxxx
GSS_S_CALL_BAD_STRUCTURE 03xxxxxx
GSS_S_CALL_INACCESSIBLE_READ 01xxxxxx
GSS_S_CALL_INACCESSIBLE_WRITE 02xxxxxx
GSS_S_COMPLETE 00000000
GSS_S_DUPLICATE_ELEMENT xx11xxxx
GSS_S_FAILURE xx0Dxxxx
GSS_S_NO_CRED xx07xxxx
GSS_S_UNAVAILABLE xx10xxxx
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)gss_add_cred(3)