gss_add_cred - element to a credential
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);
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 <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_han-
dle is NULL.
desired_name Name of the principal for which a credential
should be acquired.
desired_mech Underlying security mechanism with which the cre-
dential 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 argu-
ment is ignored if the composed credentials are
of the GSS_C_INITIATE type. Specify GSS_C_INDEFI-
NITE 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-ele-
ments from input_cred_handle. If a valid pointer
to a gss_cred_id_t is supplied for this parame-
ter, gss_add_cred() creates a new credential han-
dle that contains all credential-elements from
input_cred_handle and the newly acquired creden-
tial-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 han-
dle 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 cre-
dential 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 creden-
tials, 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 cre-
ating 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. Conse-
quently, 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 mecha-
nism 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 creden-
tial 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 out-
put_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 param-
eter is ill formed.
GSS_S_DUPLICATE_ELEMENT The credential already contains an element
for the requested mechanism that has over-
lapping 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 speci-
fied 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(7) for descriptions of the following attributes:
+-----------------------------+-----------------------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+-----------------------------+-----------------------------+
|MT-Level |Safe |
+-----------------------------+-----------------------------+
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
+---------------+------------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+------------------------+
|Availability | security/kerberos-5 |
+---------------+------------------------+
|Stability | Pass-through committed |
+---------------+------------------------+
SEE ALSO
gss_accept_sec_context(3GSS), gss_acquire_cred(3GSS), gss_init_sec_con-
text(3GSS), gss_inquire_context(3GSS), gss_inquire_cred(3GSS),
gss_release_cred(3GSS), gss_release_oid_set(3GSS), libgss(3LIB),
attributes(7)
NOTES
Source code for open source software components in Oracle Solaris can
be found at https://www.oracle.com/downloads/opensource/solaris-source-
code-downloads.html.
This software was built from source available at
https://github.com/oracle/solaris-userland. The original community
source was downloaded from http://web.mit.edu/ker-
beros/dist/krb5/1.18/krb5-1.18.4.tar.gz.
Further information about this software can be found on the open source
community website at http://web.mit.edu/kerberos/.
Solaris 11.4 30 Jun 2005 gss_add_cred(3gss)