PAM Library Functions                      pam_sm_chauthtok(3PAM)

NAME
     pam_sm_chauthtok  -  service  provider  implementation   for
     pam_chauthtok

SYNOPSIS
     cc [ flag ...] file ... -lpam [ library ... ]
     #include <security/pam_appl.h>
     #include <security/pam_modules.h>

     int  pam_sm_chauthtok(pam_handle_t  *pamh,  int  flags,  int
     argc, const char **argv);

DESCRIPTION
     In response to a call to pam_chauthtok() the  PAM  framework
     calls  pam_sm_chauthtok(3PAM) from the modules listed in the
     pam.conf(4) file.  The password management provider supplies
     the back-end functionality for this interface function.

     The pam_sm_chauthtok() function changes  the  authentication
     token  associated  with  a particular user referenced by the
     authentication handle pamh.

     The following flag may be passed to pam_chauthtok():

     PAM_SILENT
           The password service should not generate any messages.

     PAM_CHANGE_EXPIRED_AUTHTOK
           The password service should only  update  those  pass-
           words  that have aged. If this flag is not passed, the
           password service should update all passwords.

     PAM_PRELIM_CHECK
           The password service should only  perform  preliminary
           checks. No passwords should be updated.

     PAM_UPDATE_AUTHTOK
           The password service should update passwords.

     Note that  PAM_PRELIM_CHECK and   PAM_UPDATE_AUTHTOK  cannot
     be set at the same time.

     Upon successful completion of the call,  the  authentication
     token  of  the  user  will  be  ready  for change or will be
     changed, depending upon the flag,  in  accordance  with  the
     authentication scheme configured within the system.

     The argc argument represents the number  of  module  options
     passed  in from the configuration file pam.conf(4). The argv
     argument specifies the module options, which are interpreted
     and  processed  by  the password management service.  Please
     refer to the specific  module  man  pages  for  the  various

SunOS 5.8           Last change: 19 Mar 1999                    1

PAM Library Functions                      pam_sm_chauthtok(3PAM)

     available options.

     It is the responsibility of pam_sm_chauthtok() to  determine
     if  the  new  password  meets certain strength requirements.
     pam_sm_chauthtok() may continue to re-prompt the user (for a
     limited  number of times) for a new password until the pass-
     word entered meets the strength requirements.

     Before    returning,    pam_sm_chauthtok()    should    call
     pam_get_item()    and   retrieve   both    PAM_AUTHTOK   and
     PAM_OLDAUTHTOK. If both are  NULL, pam_sm_chauthtok() should
     set  them  to  the  new  and old passwords as entered by the
     user.

RETURN VALUES
     Upon successful completion,  PAM_SUCCESS must  be  returned.
     The following values may also be returned:

     PAM_PERM_DENIED
           No permission.

     PAM_AUTHTOK_ERR
           Authentication token manipulation error.

     PAM_AUTHTOK_RECOVERY_ERR
           Old authentication token cannot be recovered.

     PAM_AUTHTOK_LOCK_BUSY
           Authentication token lock busy.

     PAM_AUTHTOK_DISABLE_AGING
           Authentication token aging disabled.

     PAM_USER_UNKNOWN
           User unknown to password service.

     PAM_TRY_AGAIN
           Preliminary check by password service failed.

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

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

SunOS 5.8           Last change: 19 Mar 1999                    2

PAM Library Functions                      pam_sm_chauthtok(3PAM)

SEE ALSO
     ping(1M),          pam(3PAM),           pam_chauthtok(3PAM),
     pam_get_data(3PAM),  pam_get_item(3PAM), pam_set_data(3PAM),
     libpam(3LIB), pam.conf(4), attributes(5)

NOTES
     The PAM framework invokes the password services twice.   The
     first   time   the   modules  are  invoked  with  the  flag,
     PAM_PRELIM_CHECK.  During this stage, the  password  modules
     should  only  perform preliminary checks.  For example, they
     may ping remote name services to see if they are  ready  for
     updates.   If  a  password  module detects a transient error
     such as a remote name service temporarily  down,  it  should
     return   PAM_TRY_AGAIN  to  the  PAM  framework,  which will
     immediately return the error back to the application. If all
     password  modules pass the preliminary check, the PAM frame-
     work invokes the password  services  again  with  the  flag,
     PAM_UPDATE_AUTHTOK.  During this stage, each password module
     should proceed to  update  the  appropriate  password.   Any
     error will again be reported back to application.

     If    a     service     module     receives     the     flag
     PAM_CHANGE_EXPIRED_AUTHTOK,  it  should  check  whether  the
     password has aged or expired. If the password  has  aged  or
     expired,  then  the  service module should proceed to update
     the password. If the status indicates that the password  has
     not  yet  aged  or  expired, then the password module should
     return  PAM_IGNORE.

     If a user's password has aged or  expired,  a   PAM  account
     module could save this information as state in the authenti-
     cation handle, pamh, using pam_set_data(). The related pass-
     word management module could retrieve this information using
     pam_get_data() to determine whether or not it should  prompt
     the user to update the password for this particular module.

     The interfaces in  libpam are MT-Safe only  if  each  thread
     within  the multithreaded application uses its own  PAM han-
     dle.

SunOS 5.8           Last change: 19 Mar 1999                    3