NAME
sec_login_valid_from_keytable - Validates a login context's
identit using input from a
specified keytable file
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 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
filename 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 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 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 trys 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
SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
The idl file from which dce/sec_login.h was derived.
ERRORS
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
sec_login_validate_identity
sec_login_certify_identity
sec_login_setup_identity
sec_login_valid_and_cert_ident