Generic Security Services API Library Functions
gss_add_cred(3GSS)
NAME
gss_add_cred - add a credential-element to a credential
SYNOPSIS
cc [ flag... ] file... -lgss [ library... ]
#include
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);
PARAMETERS
The parameter descriptions for gss_add_cred() follow:
minor_status Mechanism specific status code.
input_cred_handle Credential to which the credential-
element is added. IfGSS_C_NO_CREDENTIAL is specified, the
function composes the new credential based on default behavior. While thecredential-handle is not modified by
gss_add_cred(), the underlying creden-
tial is modified ifoutput_credential_handle is NULL.
desired_name Name of the principal for which a
credential should be acquired.desired_mech Underlying security mechanism with
which the credential can be used.GSS_C_NULL_OID can be used to obtain a
default.cred_usage Flag that indicates how a credential
is used to initiate or accept security credentials. If the flag isGSS_C_ACCEPT, the credentials are used
SunOS 5.11 Last change: 30 Jun 2005 1
Generic Security Services API Library Functionsgss_add_cred(3GSS)
only to accept security credentials.If the flag is GSS_C_INITIATE, the
credentials are used only to initiate security credentials. If the flag isGSS_C_BOTH, the credentials can be
used to either initiate or accept security contexts.initiator_time_req Number of seconds that the credential
may remain valid for initiating secu-
rity contexts. This argument is ignored if the composed credentialsare of the GSS_C_ACCEPT type. 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 secu-
rity contexts. This argument is ignored if the composed credentialsare of the GSS_C_INITIATE type.
Specify GSS_C_INDEFINITE to request
that the credentials have the maximum permitted initiator lifetime.output_cred_handle Returned credential handle that con-
tains 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 that containsall credential-elements from
input_cred_handle and the newly
acquired credential-element. If NULL
is specified for this parameter, thenewly acquired credential-element is
added to the credential identified byinput_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 togss_release_cred(3GSS).
SunOS 5.11 Last change: 30 Jun 2005 2
Generic Security Services API Library Functionsgss_add_cred(3GSS)
actual_mechs Complete set of mechanisms for which
the new credential is valid. Storagefor the returned OID-set must be freed
by the application after use by a callto gss_release_oid_set(3GSS). Specify
NULL if this parameter is not required.initiator_time_rec Actual number of seconds for which the
returned credentials remain valid forinitiating contexts using the speci-
fied mechanism. If a mechanism does not support expiration of credentials,the value GSS_C_INDEFINITE is
returned. Specify NULL if this parame-
ter is not required.acceptor_time_rec Actual number of seconds for which the
returned credentials remain valid for accepting security contexts using the specified mechanism. If a mechanismdoes not support expiration of creden-
tials, the value GSS_C_INDEFINITE is
returned. Specify NULL if this parame-
ter is not required.DESCRIPTION
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 function is not intended as a function to login to the network. A function for login to the network would involve creating newmechanism-specific authentication data, rather than acquir-
ing 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 to
invoke default behavior when passed togss_init_sec_context(3GSS) if the value of cred_usage is
GSS_C_INITIATE or GSS_C_BOTH. The call is also interpreted
as a request to add a credential-element to the invoke
default behavior when passed to 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. The GSS-API provides mechanism-
SunOS 5.11 Last change: 30 Jun 2005 3
Generic Security Services API Library Functionsgss_add_cred(3GSS)
specific ways to obtain GSS-API initiator credentials
through the system login process. Consequently, the GSS-API
does not support acquiring GSS_C_INITIATE or GSS_C_BOTH
credentials by means of gss_acquire_cred(3GSS) for any name
other than the following:o GSS_C_NO_NAME
o Name produced by gss_inquire_cred(3GSS) applied to
a valid credentialo Name produced by gss_inquire_context(3GSS) applied
to an active context If credential acquisition is time consuming for a mechanism, the mechanism can choose to delay the actual acquisition until the credential is required bygss_init_sec_context(3GSS), for example, or by
gss_accept_sec_context(3GSS). Such mechanism-specific imple-
mentation decisions are invisible to the calling applica-
tion. A call to gss_inquire_cred(3GSS) immediately following
the call gss_add_cred() returns valid credential data as
well as incurring the overhead of deferred credential acquisition.The gss_add_cred() function 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. The function can also be used to add the newcredential-element to an existing credential. If the value
of the output_cred_handle parameter is NULL, the new
credential-element is 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 is
created.If the value of input_cred_handle is GSS_C_NO_CREDENTIAL,
the gss_add_cred() function composes a credential and sets
the output_cred_handle parameter based on the default
behavior. The call has the same effect as a call first madeby the application to gss_acquire_cred(3GSS) to specify the
same usage and to pass GSS_C_NO_NAME as the desired_name
parameter. Such an application call obtains an explicit credential handle that incorporates the default behaviors,then passes the credential handle to gss_add_cred(), and
finally calls gss_release_cred(3GSS) on the first credential
handle.SunOS 5.11 Last change: 30 Jun 2005 4
Generic Security Services API Library Functionsgss_add_cred(3GSS)
If the value of the input_cred_handle parameter is
GSS_C_NO_CREDENTIAL, a non-NULL value must be supplied for
the output_cred_handle parameter.
RETURN VALUES
The gss_add_cred() function can 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 isdefined. The mechanism-specific
status code reported by meansof the minor_status parameter
details the error condition.ATTRIBUTES
SunOS 5.11 Last change: 30 Jun 2005 5
Generic Security Services API Library Functionsgss_add_cred(3GSS)
See attributes(5) for descriptions of the following attri-
butes:____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| MT-Level | Safe |
|_____________________________|_____________________________|
SEE ALSO
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), libgss(3LIB), attributes(5)
Oracle Solaris Security for Developers GuideSunOS 5.11 Last change: 30 Jun 2005 6
Generic Security Services API Library Functionsgss_add_cred(3GSS)
SunOS 5.11 Last change: 30 Jun 2005 7