sec_login_valid_from_keytable(3sec)

Synopsis

#include <dce/sec_login.h>

boolean32 sec_login_valid_from_keytable(
sec_login_handle_t login_context,
unsigned32 authn_service,
void *arg,
unsigned32 try_kvno,
unsigned32 *used_kvno,
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's name and UUID, account restrictions, records of the account principal's group memberships, and the account's home directory. (See sec_intro(3sec) for more details about the login context.)

authn_service
Identifies the authentication protocol using the key. The possible authentication protocols are as follows:

rpc_c_authn_dce_secret
DCE shared-secret key authentication.

rpc_c_authn_dce_public
DCE public key authentication (reserved for future use).

arg
This parameter can specify either the local keytab file or an argument to the get_key_fn key acquisition routine of the rpc_server_register_auth_info routine.

A value of NULL specifies that the default keytab file should be used. A keytab file name specifies that that file should be used as the keytab file. You must prepend the file's absolute file name with FILE: and the file must have been created with the rgy_edit command or the sec_key_mgmt_set_key routine.

Any other value specifies an argument for the get_key_fn key acquisition routine. See the rpc_server_register_auth_info( ) reference page for more information.

try_kvno
The version number of the key in the keytab file to try first. Specify NULL to try the current version of the key.

Output

used_kvno
A pointer to a 32-bit boolean32 value that specifies the version number of the key from the keytab file that was used to successfully validate the login context, if any.

reset_passwd
A pointer to a 32-bit boolean32 value. The routine returns TRUE if the account password has expired and should 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
Authentication accomplished through the normal network authority. A login context authenticated this way will have all the network credentials it ought to have.

sec_login_auth_src_local
Authentication accomplished via local data. Authentication occurs locally if a principal's account is tailored for the local machine, or if the network authority is unavailable. Since a login contexts authenticated locally has no network credentials, it can not be used for network operations.

sec_login_auth_src_overridden
Authentication accomplished via the override facility.

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_from_keytable ( ) routine validates the login context established with sec_login_setup_identity( ). The sec_login_valid_from_keytable (~) routine obtains the principal's password from the specified keytable.

If try_kvno specifies a key version number, that version number key is tried first, otherwise the current key version number is tried first. The function tries all keys in the keytable until it finds one that validates the login context. This operation must be invoked before the network credentials can be used.

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.

Return Values
The routine returns TRUE if the login context 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_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_key_mgmt_e_key_unavailable
The requested key is not present.

sec_key_mgmt_e_authn_invalid
The authentication protocol is not valid.

sec_key_mgmt_e_unauthorized
The caller is not authorized to perform the operation.

sec_s_no_memory
Unable to allocate memory.

error_status_ok
The call was successful.

Examples
The following example illustrates use of the sec_login_valid_from_keytable( ) 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 local keytable...

if (sec_login_valid_from_keytable(login_context, authn_service, arg, try_kvno,
&used_kvno, &reset_passwd, &auth_src, &st)) {

sec_login_set_context(login_context, &st);

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

}

... 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_validate_identity(3sec)

sec_login_certify_identity(3sec)

sec_login_setup_identity(3sec)

sec_login_valid_and_cert_ident(3sec)