NAME
pam_get_authtok —
retrieve authentication
token
SYNOPSIS
#include
<sys/types.h>
#include
<security/pam_appl.h>
int
pam_get_authtok(pam_handle_t
*pamh, int item,
const char **authtok,
const char *prompt);
DESCRIPTION
Thepam_get_authtok()
function either prompts the user for an authentication token or retrieves a
cached authentication token, depending on circumstances. Either way, a pointer
to the authentication token is stored in the location pointed to by the
authtok argument, and the corresponding PAM item is
updated.
The item argument must have one of the following values:
PAM_AUTHTOK- Returns the current authentication token, or the new token when changing authentication tokens.
PAM_OLDAUTHTOK- Returns the previous authentication token when changing authentication tokens.
The prompt argument
specifies a prompt to use if no token is cached. If it is
NULL, the PAM_AUTHTOK_PROMPT
or PAM_OLDAUTHTOK_PROMPT item, as appropriate, will
be used. If that item is also NULL, a hardcoded
default prompt will be used. Additionally, when
pam_get_authtok()
is called from a service module, the prompt may be affected by module
options as described below. The prompt is then expanded using
openpam_subst(3) before it is passed to the conversation
function.
If item is set to
PAM_AUTHTOK and there is a non-null
PAM_OLDAUTHTOK item,
pam_get_authtok()
will ask the user to confirm the new token by retyping it. If there is a
mismatch, pam_get_authtok() will return
PAM_TRY_AGAIN.
MODULE OPTIONS
When called by a service module,
pam_get_authtok() will recognize the following
module options:
authtok_prompt- Prompt to use when item is set to
PAM_AUTHTOK. This option overrides both the prompt argument and thePAM_AUTHTOK_PROMPTitem. echo_pass- If the application's conversation function allows it, this lets the user see what they are typing. This should only be used for non-reusable authentication tokens.
oldauthtok_prompt- Prompt to use when item is set to
PAM_OLDAUTHTOK. This option overrides both the prompt argument and thePAM_OLDAUTHTOK_PROMPTitem. try_first_pass- If the requested item is non-null, return it without prompting the user.
Typically, the service module will verify the token, and if it does not
match, clear the item before calling
pam_get_authtok() a second time. use_first_pass- Do not prompt the user at all; just return the cached value, or
PAM_AUTH_ERRif there is none.
RETURN VALUES
The pam_get_authtok() function returns one
of the following values:
- [
PAM_SUCCESS] - Success.
- [
PAM_BAD_CONSTANT] - Bad constant.
- [
PAM_BAD_ITEM] - Unrecognized or restricted item.
- [
PAM_BUF_ERR] - Memory buffer error.
- [
PAM_CONV_ERR] - Conversation failure.
- [
PAM_SYSTEM_ERR] - System error.
- [
PAM_TRY_AGAIN] - Try again.
SEE ALSO
openpam_get_option(3), openpam_subst(3), pam(3), pam_conv(3), pam_get_item(3), pam_get_user(3), pam_strerror(3)
STANDARDS
The pam_get_authtok() function is an
OpenPAM extension.
AUTHORS
The pam_get_authtok() function and this
manual page were developed for the FreeBSD Project
by ThinkSec AS and Network Associates Laboratories, the Security Research
Division of Network Associates, Inc. under DARPA/SPAWAR contract
N66001-01-C-8035 (“CBOSS”), as part of the DARPA CHATS
research program.
The OpenPAM library is maintained by Dag-Erling Smørgrav <des@des.no>.