sec_login_setup_identity-Set up a login context for a principal/account
#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 );
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 indicating properties attributed to created login context.
The created login context.
The completion status.
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.
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.)
sec_login_release_context(), sec_login_validate_identity(), sec_login_valid_and_cert_identity().