PAM_GET_AUTHTOK(3) | Library Functions Manual | PAM_GET_AUTHTOK(3)

# 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

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

# 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 the `PAM_AUTHTOK_PROMPT` item.
`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 the `PAM_OLDAUTHTOK_PROMPT` item.
`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_ERR` if 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>.

April 30, 2017 | NetBSD 9.0