# pam_get_authtok

## NAME



           pam_get_authtok, pam_get_authtok_verify, pam_get_authtok_noverify
           - get authentication token
    


## SYNOPSIS



           **#include <security/pam_ext.h>**
    
           **int pam_get_authtok(pam_handle_t ***_pamh_**, int** _item_**,**
                               **const char ****_authtok_**, const char ***_prompt_**);**
    
           **int pam_get_authtok_noverify(pam_handle_t ***_pamh_**,**
                                        **const char ****_authtok_**,**
                                        **const char ***_prompt_**);**
    
           **int pam_get_authtok_verify(pam_handle_t ***_pamh_**,**
                                      **const char ****_authtok_**,**
                                      **const char ***_prompt_**);**
    


## DESCRIPTION



           The **pam_get_authtok** function returns the cached authentication
           token, or prompts the user if no token is currently cached. It is
           intended for internal use by Linux-PAM and PAM service modules.
           Upon successful return, _authtok_ contains a pointer to the value of
           the authentication token. Note, this is a pointer to the _actual_
           data and should **not** be _free()_ 'ed or over-written!
    
           The _prompt_ argument specifies a prompt to use if no token is
           cached. If a NULL pointer is given, **pam_get_authtok** uses
           pre-defined prompts.
    
           The following values are supported for _item_ :
    
           PAM_AUTHTOK
               Returns the current authentication token. Called from
               pam_sm_chauthtok(3) **pam_get_authtok** will ask the user to
               confirm the new token by retyping it. If a prompt was
               specified, "Retype" will be used as prefix.
    
           PAM_OLDAUTHTOK
               Returns the previous authentication token when changing
               authentication tokens.
    
           The **pam_get_authtok_noverify** function can only be used for
           changing the password (from pam_sm_chauthtok(3)). It returns the
           cached authentication token, or prompts the user if no token is
           currently cached. The difference to **pam_get_authtok** is, that this
           function does not ask a second time for the password to verify it.
           Upon successful return, _authtok_ contains a pointer to the value of
           the authentication token. Note, this is a pointer to the _actual_
           data and should **not** be _free()_ 'ed or over-written!
    
           The **pam_get_authtok_verify** function can only be used to verify a
           password for mistypes gotten by pam_get_authtok_noverify(3). This
           function asks a second time for the password and verify it with
           the password provided by _authtok_ argument. In case of an error,
           the value of _authtok_ is undefined. Else this argument will point
           to the _actual_ data and should **not** be _free()_ 'ed or over-written!
    


## OPTIONS



           **pam_get_authtok** honours the following module options:
    
           **try_first_pass**
               Before prompting the user for their password, the module first
               tries the previous stacked module's password in case that
               satisfies this module as well.
    
           **use_first_pass**
               The argument **use_first_pass** forces the module to use a
               previous stacked modules password and will never prompt the
               user - if no password is available or the password is not
               appropriate, the user will be denied access.
    
           **use_authtok**
               When password changing enforce the module to set the new token
               to the one provided by a previously stacked **password** module.
               If no token is available token changing will fail.
    
           **authtok_type=**_XXX_
               The default action is for the module to use the following
               prompts when requesting passwords: "New UNIX password: " and
               "Retype UNIX password: ". The example word _UNIX_ can be
               replaced with this option, by default it is empty.
    


## RETURN VALUES



           PAM_AUTH_ERR
               Authentication token could not be retrieved.
    
           PAM_AUTHTOK_ERR
               New authentication could not be retrieved.
    
           PAM_SUCCESS
               Authentication token was successfully retrieved.
    
           PAM_SYSTEM_ERR
               No space for an authentication token was provided.
    
           PAM_TRY_AGAIN
               New authentication tokens mismatch.
    


## STANDARDS



           The **pam_get_authtok** function is a Linux-PAM extensions.
    


* * *