pam_authtok_get(5)

NAME

     pam_authtok_get -  authentication  and  password  management
     module

SYNOPSIS

     pam_authtok_get.so.1

DESCRIPTION

     The pam_authtok_get service module provides password prompt-
     ing   funtionality   to   the   PAM   stack.  It  implements
     pam_sm_authenticate()  and   pam_sm_chauthtok(),   providing
     functionality to both the Authentication Stack and the Pass-
     word Management Stack.

  Authentication Service
     The implementation of pam_sm_authenticate(3PAM) prompts  the
     user  name  if not set and then tries to get the authentica-
     tion token from the pam handle. If the token is not set,  it
     then  prompts  the  user for a password and stores it in the
     PAM item PAM_AUTHTOK. This module is meant to be  the  first
     module on an authentication stack where users are to authen-
     ticate using a keyboard.

  Password Management Service
     Due to the nature  of  the  PAM  Password  Management  stack
     traversal  mechanism, the pam_sm_chauthtok(3PAM) function is
     called twice. Once with the PAM_PRELIM_CHECK flag,  and  one
     with the PAM_UPDATE_AUTHTOK flag.

     In the first  (PRELIM)  invocation,  the  implementation  of
     pam_sm_chauthtok(3PAM) moves the contents of the PAM_AUTHTOK
     (current authentication token) to PAM_OLDAUTHTOK, and subse-
     quentially  prompts  the  user  for a new password. This new
     password is stored in PAM_AUTHTOK.

     If a previous module has set PAM_AUTHTOK prior to the  invo-
     cation  of  pam_authtok_get,  this module turns into a NO-OP
     and immediately returns PAM_SUCCESS.

     In the second (UPDATE) invocation, the user is  prompted  to
     Re-enter  his  password. The pam_sm_chauthtok implementation
     verifies this reentered password with the password stored in
     PAM_AUTHTOK.  If  the  passwords  match,  the module returns
     PAM_SUCCESS.

     The following option can be passed to the module:

     debug syslog(3C)  debugging  information  at  the  LOG_DEBUG
           level

ERRORS

     The  authentication  service  returns  the  following  error
     codes:

     PAM_SUCCESS
           Successfully obtains authentication token

     PAM_SYSTEM_ERR
           Fails to retrieve username, username is NULL or empty

     The password management service returns the following  error
     codes:

     PAM_SUCCESS
           Successfully obtains authentication token

     PAM_AUTHTOK_ERR
           Authentication token manipulation error

ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Interface Stability         | Evolving                    |
    |_____________________________|_____________________________|
    | MT Level                    | MT-Safe with exceptions     |
    |_____________________________|_____________________________|

SEE ALSO

     pam(3PAM), pam_authenticate(3PAM), syslog(3C), libpam(3LIB),
     pam.conf(4),       attributes(5),      pam_authtok_check(5),
     pam_authtok_get(5),   pam_authtok_store(5),   pam_dhkeys(5),
     pam_passwd_auth(5),     pam_unix(5),    pam_unix_account(5),
     pam_unix_auth(5), pam_unix_session(5)

NOTES

     The interfaces in libpam(3LIB)  are  MT-Safe  only  if  each
     thread  within  the  multi-threaded application uses its own
     PAM handle.

     The pam_unix(5) module might not be supported  in  a  future
     release.    Similar    functionality    is    provided    by
     pam_authtok_check(5),                    pam_authtok_get(5),
     pam_authtok_store(5),   pam_dhkeys(5),   pam_passwd_auth(5),
     pam_unix_account(5),          pam_unix_auth(5),          and
     pam_unix_session(5).