gss_acquire_cred(3) Library Functions Manual gss_acquire_cred(3)NAME
gss_acquire_cred() - allow an application to acquire a handle for an existing, named credential
SYNOPSIS DESCRIPTION
The routine allows an application to obtain a handle for a pre-existing credential by name. The credentials could be either an ACCEPT,
INITIATE, or BOTH. The application then passes the credential handle to either the or the routine. If desired_name is the call is inter-
preted as a request for a credential handle that will invoke default behavior.
Input Parameters
desired_name Specifies the principal name to use for the credential.
time_req Number of seconds that credentials remain valid. Specify to request that the credentials have the maximum permitted
lifetime.
desired_mechs Specifies the OID set for the security mechanism to use with the credential. To help ensure portability of your
application, request the default security mechanism by specifying
cred_usage Specify one of the following:
Specifies credentials that the context initiator can use to either initiate or accept security contexts.
Specifies credentials that the context initiator can use only to initiate
security contexts.
Specifies credentials that the context initiator can use only to accept
security contexts.
Output Parameters
output_cred_handle Returns the handle for the return credential.
actual_mechs Returns a set of mechanisms for which the credential is valid. This information is optional. If you do not want a
set of mechanisms returned, specify NULL.
time_rec Returns the actual number of seconds for which the return credential remains valid. This information is optional.
If the actual number of seconds is not required, specify NULL.
minor_status Returns a status code from the security mechanism.
STATUS CODES
The following list explains the GSS status codes that can be returned:
The routine was completed successfully.
The requested security mechanism is unsupported or unavailable.
The name passed by the desired_name parameter is unsupported.
An invalid name was passed by the
desired_name parameter.
The credentials could not be acquired, because they have expired.
No credentials were found for the specified name.
The routine failed. See the
minor_status parameter return value for more information.
AUTHOR
was developed by Sun Microsystems, Inc.
SEE ALSO gss_init_sec_context(3).
The manpages for DCE-GSSAPI are included with the DCE-CoreTools product. To see those manpages add to
gss_acquire_cred(3)
Check Out this Related Man Page
gss_add_cred(3GSS) 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 underly-
ing 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-ele-
ment. If NULL is specified for this parameter, the newly acquired credential-element is added to the credential iden-
tified 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 deci-
sions 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 addi-
tion 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 param-
eter.
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
SunOS 5.11 30 Jun 2005 gss_add_cred(3GSS)