 |
Index for
Section 3 |
|
 |
Alphabetical
listing for C |
|
 |
Bottom of
page |
|
csf_gss_acq_user(3)
NAME
csf_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
minor_status
Kerberos 5 error code.
user_name
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.
desired_mechs
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 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:
CSF_GSS_C_ACQ_USER_OPT_CCNAME
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.
CSF_GSS_C_ACQ_USER_OPT_KTNAME
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.
CSF_GSS_C_ACQ_USER_OPT_LIFETIME
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.
CSF_GSS_C_ACQ_USER_OPT_RENEWABLE
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:
CSF_GSS_C_ACQ_USER_OPT_ALWAYS_FETCH
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.
CSF_GSS_C_ACQ_USER_OPT_DES3
Specifies the use of DES3 encryption for obtaining user
credentials. ActiveTRUST Security Server must be configured
appropriately or an error may result.
CSF_GSS_C_ACQ_USER_OPT_FORWARDABLE
Specifies forwardable credentials.
For Kerberos credentials, use this option to request a
forwardable TGT.
CSF_GSS_C_ACQ_USER_OPT_NOPREAUTH
Skips preauthentication when obtaining credentials.
CSF_GSS_C_ACQ_USER_OPT_PROXIABLE
Specifies proxiable credentials.
For Kerberos credentials, use this option to request either a
proxiable TGT or a proxy service ticket.
CSF_GSS_C_ACQ_USER_OPT_SVCKEY
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.
user_response
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 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().
user_prompt
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().
user_label
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().
prompt_state
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:
CSF_GSS_C_USER_STATE_CHALLENGE_ECHO
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.
CSF_GSS_C_USER_STATE_CHALLENGE_NOECHO
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.
CSF_GSS_C_USER_STATE_PASSWORD_ECHO
Indicates that the mechanism requires a password, and the user
response should be echoed as it is entered.
CSF_GSS_C_USER_STATE_PASSWORD_NOECHO
Indicates that the Kerberos 5 mechanism requires a password,
and that the user response should not be echoed as it is
entered.
CSF_GSS_C_USER_STATE_OTP_ECHO
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.
CSF_GSS_C_USER_STATE_OTP_NOECHO
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.
prompting_mech
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.
pwd_exp_time
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
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.
DESCRIPTION
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.
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 supported
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)
|
Index for
Section 3 |
|
|
Alphabetical
listing for C |
|
 |
Top of
page |
|