.\" Generated from pam_get_authtok.c by gendoc.pl
.Dd June 27, 2023
.Dt PAM_GET_AUTHTOK 3
.Os
.Sh NAME
.Nm pam_get_authtok
.Nd retrieve authentication token
.Sh SYNOPSIS
.In sys/types.h
.In security/pam_appl.h
.Ft "int"
.Fn pam_get_authtok "pam_handle_t *pamh" "int item" "const char **authtok" "const char *prompt"
.Sh DESCRIPTION
The
.Fn pam_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
.Fa authtok
argument, and the corresponding PAM
item is updated.
.Pp
The
.Fa item
argument must have one of the following values:
.Bl -tag -width 18n
.It Dv PAM_AUTHTOK
Returns the current authentication token, or the new token
when changing authentication tokens.
.It Dv PAM_OLDAUTHTOK
Returns the previous authentication token when changing
authentication tokens.
.El
.Pp
The
.Fa prompt
argument specifies a prompt to use if no token is cached.
If it is
.Dv NULL ,
the
.Dv PAM_AUTHTOK_PROMPT
or
.Dv PAM_OLDAUTHTOK_PROMPT
item,
as appropriate, will be used.
If that item is also
.Dv NULL ,
a hardcoded default prompt will be used.
Additionally, when
.Fn 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
.Xr openpam_subst 3
before it is passed to
the conversation function.
.Pp
If
.Fa item
is set to
.Dv PAM_AUTHTOK
and there is a non-null
.Dv PAM_OLDAUTHTOK
item,
.Fn pam_get_authtok
will ask the user to confirm the new token by
retyping it.
If there is a mismatch,
.Fn pam_get_authtok
will return
.Dv PAM_TRY_AGAIN .
.Sh MODULE OPTIONS
When called by a service module,
.Fn pam_get_authtok
will recognize the
following module options:
.Bl -tag -width 18n
.It Dv authtok_prompt
Prompt to use when
.Fa item
is set to
.Dv PAM_AUTHTOK .
This option overrides both the
.Fa prompt
argument and the
.Dv PAM_AUTHTOK_PROMPT
item.
.It Dv 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.
.It Dv oldauthtok_prompt
Prompt to use when
.Fa item
is set to
.Dv PAM_OLDAUTHTOK .
This option overrides both the
.Fa prompt
argument and the
.Dv PAM_OLDAUTHTOK_PROMPT
item.
.It Dv 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
.Fn pam_get_authtok
a second time.
.It Dv use_first_pass
Do not prompt the user at all; just return the cached
value, or
.Dv PAM_AUTH_ERR
if there is none.
.El
.Sh RETURN VALUES
The
.Fn pam_get_authtok
function returns one of the following values:
.Bl -tag -width 18n
.It Bq Er PAM_SUCCESS
Success.
.It Bq Er PAM_BAD_CONSTANT
Bad constant.
.It Bq Er PAM_BAD_ITEM
Unrecognized or restricted item.
.It Bq Er PAM_BUF_ERR
Memory buffer error.
.It Bq Er PAM_CONV_ERR
Conversation failure.
.It Bq Er PAM_SYSTEM_ERR
System error.
.It Bq Er PAM_TRY_AGAIN
Try again.
.El
.Sh SEE ALSO
.Xr openpam_get_option 3 ,
.Xr openpam_subst 3 ,
.Xr pam 3 ,
.Xr pam_conv 3 ,
.Xr pam_get_item 3 ,
.Xr pam_get_user 3 ,
.Xr pam_strerror 3
.Sh STANDARDS
The
.Fn pam_get_authtok
function is an OpenPAM extension.
.Sh AUTHORS
The
.Fn pam_get_authtok
function and this manual page were
developed for the
.Fx
Project by ThinkSec AS and Network Associates Laboratories, the
Security Research Division of Network Associates, Inc.\& under
DARPA/SPAWAR contract N66001-01-C-8035
.Pq Dq CBOSS ,
as part of the DARPA CHATS research program.
.Pp
The OpenPAM library is maintained by
.An Dag-Erling Sm\(/orgrav Aq Mt des@des.no .