GSS_ADD_CRED(3GSS) Generic Security Services API Library Functions


NAME


gss_add_cred - add a credential-element to a credential

SYNOPSIS


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);


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. If GSS_C_NO_CREDENTIAL is specified, the
function composes the new credential based on
default behavior. While the credential-handle is
not modified by gss_add_cred(), the underlying
credential is modified if output_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 is GSS_C_ACCEPT, the credentials are used only
to accept security credentials. If the flag is
GSS_C_INITIATE, the credentials are used only to
initiate security credentials. If the flag is
GSS_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 security contexts. This
argument is ignored if the composed credentials are
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 security contexts. This
argument is ignored if the composed credentials are
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 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 that
contains 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 is
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).


actual_mechs
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.


initiator_time_rec
Actual number of seconds for which the returned
credentials remain valid for initiating contexts
using the specified mechanism. If a mechanism does
not support expiration of credentials, the value
GSS_C_INDEFINITE is returned. Specify NULL if this
parameter 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
mechanism does not support expiration of
credentials, the value GSS_C_INDEFINITE is
returned. Specify NULL if this parameter 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
new mechanism-specific authentication data, rather than 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 to 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. 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-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
credential

o 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 by gss_init_sec_context(3GSS), for example, or by
gss_accept_sec_context(3GSS). Such mechanism-specific implementation
decisions are invisible to the calling application. 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 new credential-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 made by 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.


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 is
defined. The mechanism-specific status code
reported by means of the minor_status
parameter details the error condition.


ATTRIBUTES


See attributes(5) for descriptions of the following attributes:


+---------------+-----------------+
|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)


Solaris Security for Developers Guide


June 30, 2005 GSS_ADD_CRED(3GSS)