NAME

sec_login_setup_identity-Set up a login context for a principal/account

SYNOPSIS

#include <dce/sec_login.h>

boolean32 sec_login_setup_identity (
    unsigned_char_p_t principal,
    sec_login_flags_t flags,
    sec_login_handle_t *login_context,
    error_status_t *status );

PARAMETERS

Input

principal

Name of principal/account to which created login context is to refer. (Recall that an account is uniquely identified by its principal name component.)

flags

Flags indicating properties attributed to created login context.

Output

login_context

The created login context.

status

The completion status.

DESCRIPTION

The sec_login_setup_identity() routine sets up a login context; that is, creates, in the address space of the calling process, an (unvalidated and uncertified) login context for the specified principal/account.

A login context created by this routine is not usable for making protected RPCs (see rpc_binding_set_auth_info()) until it has been validated, usually by sec_login_validate_identity() (see also sec_login_valid_and_cert_identity()). In this sense, sec_login_setup_identity() and sec_login_validate_identity() are the two halves of a single logical operation: together they collect the data needed to establish a trusted, authenticated identity. (The rationale for making the routines independent is to make sure passwords are subjected to minimal exposure, such as sending them unprotected in a message, or retaining them in local memory for longer than absolutely necessary; for example, during a long networking delay that might be caused by an attacker.)

The memory storage for the created login context is dynamically allocated (the sec_login_release_context() function is used to free it).

In typical implementations, in the case of the Kerberos authentication service (the only authentication service currently supported by DCE), this routine calls a kds_request() RPC operation, returning a KDS Response message protected in the long-term key of the specified principal/account, which cannot therefore be used (much less trusted) until it has been decrypted (using sec_login_validate_identity()). (Note that this routine only contacts the KDS (of the cell in which the specified principal/account is registered), not the PS-thus, it manipulates a TGT, not a PTGT.) An alternative implementation, in environments where holding the password in memory for a longer period of time is not as large a threat, is to postpone the kds_request() call until sec_login_validate_identity() is invoked.

RETURN VALUES

The routine returns non-0 (TRUE) if the login context has been successfully created, otherwise it returns 0 (FALSE). (In the success case, this return value is redundant with error_status_ok.)

ERRORS

error_status_ok

sec_login_s_no_memory

sec_login_s_internal_error

sec_rgy_object_not_found

sec_rgy_server_unavailable

SEE ALSO

Functions: sec_login_release_context(), sec_login_validate_identity(), sec_login_valid_and_cert_identity().

Protocols: kds_request().