sec_login_validate_identity(3sec)

Synopsis

#include <dce/sec_login.h>

boolean32 sec_login_validate_identity(
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
How the login context was authorized. The sec_login_auth_src_t data type distinguishes the various ways the login context was authorized. There are three possible values:

sec_login_auth_src_network
sec_login_auth_src_local
sec_login_auth_src_overridden

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_validate_identity( ) routine validates the login context established with sec_login_setup_identity( ). This operation must be invoked before the network credentials can be used. The caller must supply the user's password in a sec_passwd_rec_t as input with the passwd parameter. The following example sets up a plaintext password for the passwd parameter:

sec_passwd_str_t tmp_passwd;

passwd.version_number = sec_passwd_c_version_none;
passwdepper = NULL;
passwd.key.key_type = sec_passwd_plain;

strncpy((char *) tmp_passwd, (char *) my_passwd, sec_passwd_str_max_len);
tmp_passwd[sec_passwd_str_max_len] = ' ';
passwd_rec.key.tagged_unionlain = &(tmp_passwd[0]);

When a network identity is set, only state information for network operations has been established. The local operating system identity has not been modified. It is the responsibility of the caller to establish any local operating identity state.

The sec_login_setup_identity( ) operation and the sec_login_validate_identity( ) operation are two halves of a single logical operation. Together they collect the identity data needed to establish an authenticated identity. The operations are independent so the user's password need not be sent across the network. The identity validation performed by sec_login_validate_identity( ) is a local operation.

Notes
A context is not secure and must not be set or exported until the authentication service is itself authenticated with the sec_login_certify_identity( ) call.

System login programs that set local operating system identity using data extracted from a login context should use sec_login_valid_and_cert_ident( ) instead of sec_login_validate_identity( ).

If the Security server and client clocks are not synchronized to within 2 to 3 minutes of each other, this call can return a password validation error.

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
There is no data with which to compare the input string.

sec_login_s_acct_invalid
The account is invalid or has expired.

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_validate_identity( ) routine as part of a straightforward login process:

if (sec_login_setup_identity(user_name, sec_login_no_flags, &login_context,
&st)) {
... get password from user...

if (sec_login_validate_identity(login_context, password,
&reset_passwd, &auth_src, &st)) {

if (!sec_login_certify_identity(login_context, &st))
exit(error_weird_auth_svc);

sec_login_set_context(login_context, &st);

if (auth_src != sec_login_auth_src_network)
printf("no network credentials");

if (reset_passwd) {
... get new password from user, reset registry record ...

};

sec_login_get_pwent(login_context, &pw_entry, &st);

if (pw_entry.pw_expire < todays_date) {
sec_login_purge_context(&login_context, &st);
exit(0)
}

... any other application specific login valid actions ...
}

} else {
sec_login_purge_context(&login_context, &st);

... application specific login failure actions ...
}
}

Related Information
Functions:

sec_intro(3sec)

sec_login_certify_identity(3sec)

sec_login_setup_identity(3sec)

sec_login_valid_and_cert_ident(3sec)