pam_get_authtok(3) - NetBSD Manual Pages

Command:
Section:
Arch:
Collection:
>>>
PAM_GET_AUTHTOK(3)      NetBSD 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 authentica-
     tion token or retrieves a cached authentication token, depending on cir-
     cumstances.  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 chang-
                         ing 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>.

NetBSD 9.1                      April 30, 2017                      NetBSD 9.1