sec_login_valid_and_cert_ident(3sec)

Synopsis

#include <dce/sec_login.h>

boolean32 sec_login_valid_and_cert_ident(
sec_login_handle_t login_context,
sec_passwd_rec_t *passwd,
boolean32 *reset_passwd,

sec_login_auth_src_t *auth_src,
error_status_t *status);

Parameters

Input

login_context
An opaque handle to login context data. The login context contains, among other data, the account principal name and UUID, account restrictions, records of group membership, and the process home directory. (See sec_intro(3sec) for more details about the login context.)

passwd
A password record to be checked against the password in the principal's registry account. The routine returns TRUE if the two match.

The contents of the passwd parameter are erased after the call has finished processing it.

Output

reset_passwd
A pointer to a 32-bit boolean32 value. The routine returns TRUE if the account password has expired and must be reset.

auth_src
A 32-bit set of flags identifying the source of the authentication. Upon return after successful authentication, the flags in auth_src indicate what authority was used to validate the login context. If the authentication was accomplished with the network authority, the sec_login_auth_src_network flag is set, and the process login context has credentials to use the network. If the authentication was accomplished with local data only (either the principal's account is tailored for the local machine with overrides, or the network authority is unavailable), the sec_login_auth_src_local flag is set. Login contexts that are authenticated locally may not be used to establish network credentials because they have none.

status
A pointer to the completion status. On successful completion, status is assigned error_status_ok. Otherwise, it returns an error.

Description
The sec_login_valid_and_cert_ident( ) routine validates and certifies a login context established with sec_login_setup_identity( ). The caller must supply the user's password as input with the passwd parameter.

This routine combines the operations of the sec_login_validate_identity( ) and sec_login_certify_identity( ) routines. It is intended for use by system login programs that need to extract trustworthy operating system credentials for use in setting the local identity for a process. This operation destroys the contents of the passwd input parameter.

If the network security service is unavailable or if the user's password has been overridden on the host, a locally authenticated context is created, and the auth_src parameter is set to sec_login_auth_src_local. Data extracted from a locally authenticated context may be used to set the local OS identity, but it cannot be used to establish network credentials.

This routine is a privileged operation.

Return Values
The routine returns TRUE if the login identity has been successfully validated.

Files

/usr/include/dce/sec_login.idl
The idl file from which dce/sec_login.h was derived.

Errors

The following describes a partial list of errors that might be returned. Refer to the OSF DCE Problem Determination Guide for complete descriptions of all error messages.

sec_rgy_passwd_invalid
The input string does not match the account password.

sec_rgy_server_unavailable
The DCE Registry Server is unavailable.

sec_login_s_acct_invalid
The account is invalid or has expired.

sec_login_s_privileged
This is a privileged operation and was invoked by an unprivileged process.

sec_login_s_null_password
The input string is NULL.

sec_login_s_default_use
The input context was the default context, which cannot be validated.

sec_login_s_already_valid
The login context has already been validated.

sec_login_s_unsupp_passwd_type
The password type is not supported.

sec_login_s_no_memory
Not enough memory is available to complete the operation.

sec_login_s_preauth_failed
Preauthentication failure.

sec_pk_e_domain_unsupported
The DCE login domain is not supported by the personal security mechanism.

sec_pk_e_device_error
Personal security mechanism device error.

sec_pk_e_usage_unsupported
A private key of the required type was not located in the personal security mechanism.

sec_pk_e_unauthorized
The password is invalid for personal security mechanism access.

error_status_ok
The call was successful.

Examples
The following example illustrates use of the sec_login_valid_and_cert_ident( ) routine as part of a system login process:

if (sec_login_setup_identity(<user>,
sec_login_no_flags, &login_context, &st)) {
... get password ...
if (sec_login_valid_and_cert_ident(login_context,
password, &st)) {
if (auth_src == sec_login_auth_src_network) {
if (GOOD_STATUS(&st)
sec_login_set_context(login_context);
}
}
if (reset_passwd) {
... reset the user's password ...
if (passwd_reset_fails) {
sec_login_purge_context(login_context)
... application login failure actions ...
}
... application specific login valid actions ...
}
}

Related Information
Functions:

sec_intro(3sec)

sec_login_certify_identity(3sec)

sec_login_setup_identity(3sec)

sec_login_validate_identity(3sec)