The
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
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.