|
|
csf_gss_acq_user(3)
Contents
|
csf_gss_acq_user - acquire a user's credentials prior to
initiating a security context
#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 );
Kerberos 5 error code. Internal form name of the user for
whom credentials 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
implementation 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 settings
and the required syntax for this parameter, see the
Configuration 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
Configuration section of the Developer Pack Installation
Guide. Specifies 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 renewtime
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
password and other authentication information,
using the prompt and label information returned.
Specifies the use of DES3 encryption 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 forwardable 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 contain 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 application 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
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(). Buffer used by the Kerberos 5
security mechanism to pass information 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 mechanism
requires a password, and the user response
should be echoed as it is entered. Indicates that
the Kerberos 5 mechanism requires a password, and
that the user response should not be echoed as it
is entered. Indicates that the Kerberos 5 mechanism
has an associated one-time password (OTP)
hardware authentication 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 implementation
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 applicationspecific
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 credentials, a
value of -1 is returned. To force the return of the
expiration time, use the option
CSF_GSS_ACQ_USER_OPT_ALWAYS_FETCH.
The csf_gss_acq_user() function is an extension that
acquires user credentials 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
forwardable 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 credentials.
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 constructed. 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 processing 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 associated 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.
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 [Toc] [Back] This function is an extension of the GSS-API standard that
is not supported by other GSS-API implementations.
Functions: csf_gss_inq_user(3), csf_gss_release_user(3),
gss_import_name(3), gss_release_buffer(3)
csf_gss_acq_user(3)
[ Back ] |
