Manual Pages for UNIX Operating System command usage for man pam_sm_chauthtok

PAM Library Functions                      pam_sm_chauthtok(3PAM)



NAME
     pam_sm_chauthtok  -  service  provider  implementation   for
     pam_chauthtok

SYNOPSIS
     cc [ flag ...] file ... -lpam [ library ... ]
     #include 
     #include 

     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  passwords
                                   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_NO_AUTHTOK_CHECK          The  password  service  should
                                   not perform conformance checks
                                   on the structure of the  pass-
                                   word.  Conformance  checks  do
                                   not apply to verification that
                                   the  same password was entered
                                   during both passes.



SunOS 5.11           Last change: 1 Mar 2005                    1






PAM Library Functions                      pam_sm_chauthtok(3PAM)



     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
     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  manipula-
                                  tion error.


     PAM_AUTHTOK_RECOVERY_ERR     Old authentication token cannot
                                  be recovered.






SunOS 5.11           Last change: 1 Mar 2005                    2






PAM Library Functions                      pam_sm_chauthtok(3PAM)



     PAM_AUTHTOK_LOCK_BUSY        Authentication token lock busy.


     PAM_AUTHTOK_DISABLE_AGING    Authentication token aging dis-
                                  abled.


     PAM_USER_UNKNOWN             User unknown to  password  ser-
                                  vice.


     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         | Committed                   |
    |_____________________________|_____________________________|
    | MT-Level                    | MT-Safe with exceptions     |
    |_____________________________|_____________________________|


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





SunOS 5.11           Last change: 1 Mar 2005                    3






PAM Library Functions                      pam_sm_chauthtok(3PAM)



     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.


     If the PAM_REPOSITORY item_type is set and a service  module
     does  not  recognize  the  type, the service module does not
     process any information,  and  returns  PAM_IGNORE.  If  the
     PAM_REPOSITORY  item_type  is not set, a service module per-
     forms its default action.




























SunOS 5.11           Last change: 1 Mar 2005                    4