csf_gss_acq_user(3)csf_gss_acq_user(3)NAMEcsf_gss_acq_user - acquire a user's credentials prior to initiating a
security context
SYNOPSIS
#include <gssapi/gssapi.h>
OM_uint32 csf_gss_acq_user (
OM_uint32 * minor_status,
const gss_name_t user_name,
const gss_OID_set desired_mechs,
const csf_gss_opts_t options,
const gss_buffer_t user_response,
csf_gss_user_t * user,
gss_buffer_t user_prompt,
gss_buffer_t user_label,
i_32 * prompt_state,
gss_OID * prompting_mech,
time_t * pwd_exp_time );
PARAMETERS
Kerberos 5 error code. Internal form name of the user for whom creden‐
tials are being acquired. This name must be obtained beforehand using
gss_import_name().
Specify GSS_C_NO_NAME to obtain the default that is either the
default principal in the credentials cache or the user's login
name. Object identifier (OID) list of security mechanisms that
can be used to acquire user credentials. The user must be
authorized to use the requested mechanisms. The HP implementa‐
tion of the GSS-API supports Kerberos 5.
Specify GSS_C_NO_OID_SET to select the default mechanism.
Options that determine how user credentials are acquired.
Description contains information on storing and invoking these
options. Specify CSF_GSS_C_ACQ_USER_OPT_NONE to request a ticket
with no special options.
The following options require an associated value: Specifies the
credentials cache file name in string format.
Environment variables (CSFC5CCNAME on UNIX) or registry settings
(CredCache key on Windows) can affect the location of this file
for the entire application. For more information on these set‐
tings and the required syntax for this parameter, see the Con‐
figuration section of the Developer Pack Installation Guide.
Specifies the service key table file name in string format.
Environment variables (CSFC5KTNAME on UNIX) or registry settings
(KeyTab key on Windows) can affect the location of this file for
the entire application. For more information on these settings
and the required syntax for this parameter, see the Configura‐
tion section of the Developer Pack Installation Guide. Speci‐
fies the credential's lifetime in string format: #w#d#h#m#s,
where # is the integer value, w is weeks, d is days, h is hours,
m is minutes, and s is seconds. No spaces are allowed in the
lifetime string. Specifies renewable credentials, with the
renew time in string format: #w#d#h#m#s, where # is the integer
value, w is weeks, d is days, h is hours, m is minutes, and s is
seconds. No spaces are allowed in the renew-time string.
For Kerberos credentials, use this option to request either
renewable TGT or service ticket.
The following options do not require an associated value: Forces
csf_gss_acq_user() to obtain new credentials regardless of
whether valid credentials exist at the time of the call. If this
option is set, an application must prompt the user for a pass‐
word and other authentication information, using the prompt and
label information returned. Specifies the use of DES3 encryp‐
tion for obtaining user credentials. ActiveTRUST Security
Server must be configured appropriately or an error may result.
Specifies forwardable credentials.
For Kerberos credentials, use this option to request a forward‐
able TGT. Skips preauthentication when obtaining credentials.
Specifies proxiable credentials.
For Kerberos credentials, use this option to request either a
proxiable TGT or a proxy service ticket. Obtains credentials
using a key in the service key table file, rather than prompting
for a password.
This option may not be used with CSF_GSS_C_ACQ_USER_OPT_ENCTYPE.
Buffer used to return an application response to a user prompt
from the Kerberos 5 security mechanism. Make sure to overwrite
the data in the response buffer after use, because it can con‐
tain a password that could be compromised.
The application must specify GSS_C_NO_BUFFER on the first call
to csf_gss_acq_user(). User context being acquired. The appli‐
cation must initialize the value of this parameter to
CSF_GSS_C_NO_USER on the first call.
The application must release the storage associated with this
parameter with a call to csf_gss_release_user(). Buffer used by
the Kerberos 5 security mechanism to pass prompts to the appli‐
cation. Any information returned must be displayed to the user.
This buffer is empty if no prompting is occurring.
The application must release this buffer with a call to
gss_release_buffer() after each call to csf_gss_acq_user().
Buffer used by the Kerberos 5 security mechanism to pass infor‐
mation regarding the prompting process to the application. Any
information returned must be displayed to the user. This buffer
is empty if no prompting is occurring.
The application must release this buffer with a call to
gss_release_buffer() after each call to csf_gss_acq_user().
Pointer to an integer used by the security mechanism to pass
prompt state information to the application. The information
contained in this parameter can be used by the application to
make decisions about the prompting that may need to occur.
On the first call, initialize the value of this parameter to
CSF_GSS_C_USER_STATE_NULL. Do not pass in a NULL value. As an
example, initialize this parameter as:
int prompt_state=CSF_GSS_C_USER_STATE_NULL
The possible return states are: Indicates that the Kerberos 5
mechanism requires a response to a challenge, and that the user
response should be echoed as it is entered.
This state can be used for hardware authentication challenge and
response systems. Indicates that the Kerberos 5 mechanism
requires a response to a challenge, and that the user response
should not be echoed as it is entered. Indicates that the mech‐
anism requires a password, and the user response should be
echoed as it is entered. Indicates that the Kerberos 5 mecha‐
nism requires a password, and that the user response should not
be echoed as it is entered. Indicates that the Kerberos 5 mech‐
anism has an associated one-time password (OTP) hardware authen‐
tication token issuing a request for information, and that the
user response should be echoed as it is entered. Indicates that
the Kerberos 5 mechanism has an associated one-time password
hardware authentication token issuing a request for information,
and that the user response should not be echoed as it is
entered. Security mechanism issuing the prompt. The HP imple‐
mentation of the GSS-API supports Kerberos 5.
The OID is allocated from static memory and must not be released
by the application. Expiration time of the user's password,
expressed in seconds. This information can be processed by the
application and displayed to the user in an application-specific
format. For example, when coding in C, ctime() can be used to
convert the value of this parameter to a date string.
Password expiration information is returned only if a user does
not have valid credentials. If new credentials are required, the
password expiration time is returned. If the user has valid cre‐
dentials, a value of -1 is returned. To force the return of the
expiration time, use the option
CSF_GSS_ACQ_USER_OPT_ALWAYS_FETCH.
DESCRIPTION
The csf_gss_acq_user() function is an extension that acquires user cre‐
dentials using either secret-key or public-key authentication with DES
or, optionally, DES3 encryption.
This function constructs a credentials cache for the user if it does
not exist. If the credentials cache does exist but contains invalid
credentials for the user, the cache is re-initialized. Credentials are
considered invalid if their characteristics do not match the criteria
of the desired credentials (identity, lifetime, flags such as forward‐
able or renewable, and encryption type such as DES or DES3).
Note
Information on the types of Kerberos tickets (forwardable, proxiable,
etc.) is provided in Security Server Administration Guide.
If the credentials cache does contain valid credentials for the user,
it is not changed (unless the CSF_GSS_C_ACQ_USER_OPT_ALWAYS_FETCH
option is selected).
Note
If the csf_gss_acq_user() function will destroy the credentials cache,
the application must be aware of other applications on the same system
and ensure that no other application is using the credentials cache.
To use the csf_gss_acq_user() function with Kerberos 5: Specify the
rfc_krb5_c_OID_set as the security mechanism. Select the appropriate
acquisition options and, if necessary, provide an associated value.
Respond to prompts. The csf_gss_acq_user() function returns parameters
that identify the security mechanism issuing a prompt, the state
desired (how the prompt should be processed), and any user prompt.
The csf_gss_acq_user() function may need to be called iteratively: If
it returns GSS_S_COMPLETE, the function has completed its task. If it
returns GSS_S_CONTINUE_NEEDED, one or more prompts from the security
mechanism must be satisfied. Values for the user_name, desired_mechs,
user, prompt_state, options, and prompting_mech parameters must be the
same across multiple calls to the same function.
An application can specify one or more options for acquiring user cre‐
dentials.
The following type definition shows the data structure used to store a
single option. typedef struct csf_gss_mech_opt_desc_struct {
gss_OID mechOID; /* Mech to specify option for */
OM_uint32 id; /* Identifier of option */
void * val; /* Value associated with option */
/* if appropriate */ } csf_gss_mech_opt_desc,
*csf_gss_opts_t;
An array of these structures, one for each option desired, must be con‐
structed. Initialize the mechOID field of the last record of the array
to GSS_C_NO_OID.
The following example C code fragment shows how to use options.
csf_gss_opts_t opts; #define NUM_OPTS_SET 3
/* * Allocate memory across mechanisms to set 2 options. Since you *
must NULL-terminate the array, allocate one more array element * than
that. */ opts = (csf_gss_opts_t) malloc(NUM_OPTS_SET *
sizeof(csf_gss_mech_opt_desc)); /* * Since the first occurrence of a
NULL mechanism OID field signals * csf_gss_acq_user() to stop process‐
ing options, initialize these * fields to GSS_C_NO_OID. This practice
will help prevent the call * searching outside of the array bounds. */
for (i = 0; i < NUM_OPTS_SET; i++)
opts[i].mechOID = GSS_C_NO_OID; /* Set mechs and their options */
opts[0].mechOID = rfc_krb5_c_OID; /* Kerb 5 mechanism options */
opts[0].id = CSF_GSS_C_ACQ_USER_OPT_LIFETIME; /* Set lifetime */
opts[0].val = (void*)"9h"; opts[1].mechOID = rfc_krb5_c_OID; opts[1].id
= CSF_GSS_C_ACQ_USER_OPT_FORWARDABLE; /* Make TGT forwardable*/ /* No
value associated with this option */
/* Acquire the user */ csf_gss_acq_user(..., opts,...); /* Free the
memory */ free(opts);
To avoid memory leaks, the application must: Release the storage asso‐
ciated with the user parameter with a call to csf_gss_release_user()
Release the buffers associated with the user_prompt and user_label
parameters with gss_release_buffer() after each call.
RETURN VALUES
GSS_S_BAD_MECH xx01xxxx
GSS_S_CALL_BAD_STRUCTURE 03xxxxxx
GSS_S_CALL_INACCESSIBLE_READ 01xxxxxx
GSS_S_CALL_INACCESSIBLE_WRITE 02xxxxxx
GSS_S_COMPLETE 00000000
GSS_S_CONTINUE_NEEDED xxxx0001
GSS_S_FAILURE xx0Dxxxx
PORTABILITY CONSIDERATIONS
This function is an extension of the GSS-API standard that is not sup‐
ported by other GSS-API implementations.
SEE ALSO
Functions: csf_gss_inq_user(3), csf_gss_release_user(3),
gss_import_name(3), gss_release_buffer(3)csf_gss_acq_user(3)
