PAM Library Functions                        pam_sm_setcred(3PAM)

NAME
     pam_sm_setcred  -  service   provider   implementation   for
     pam_setcred

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

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

DESCRIPTION
     In response to a call to pam_setcred(3PAM), the  PAM  frame-
     work  calls  pam_sm_setcred() from the modules listed in the
     pam.conf(4) file.  The authentication provider supplies  the
     back-end functionality for this interface function.

     The pam_sm_setcred() function is called to set  the  creden-
     tials of the current user associated with the authentication
     handle, pamh. The following flags may be set  in  the  flags
     field.    Note  that  the  first  four  flags  are  mutually
     exclusive:

     PAM_ESTABLISH_CRED
           Set user credentials for the authentication service.

     PAM_DELETE_CRED
           Delete user credentials associated with the  authenti-
           cation service.

     PAM_REINITIALIZE_CRED
           Reinitialize user credentials.

     PAM_REFRESH_CRED
           Extend lifetime of user credentials.

     PAM_SILENT
           Authentication service should not generate messages

     If no flag is set,   PAM_ESTABLISH  _CRED  is  used  as  the
     default.

     The argc argument represents the number  of  module  options
     passed  in  from  the  configuration  file pam.conf(4). argv
     specifies the module options, which are interpreted and pro-
     cessed by the authentication service.
      If an unknown option is passed to  the   module,  an  error
     should be logged and the option ignored.

     If the  PAM_SILENT flag is not  set,  then  pam_sm_setcred()
     should  print  any  failure  status  from  the corresponding

SunOS 5.8           Last change: 13 Oct 1998                    1

PAM Library Functions                        pam_sm_setcred(3PAM)

     pam_sm_authenticate() function using the conversation  func-
     tion.

     The authentication status (success or reason for failure) is
     saved  as module-specific state in the authentication handle
     by the authentication module. The status should be retrieved
     using  pam_get_data(), and used to determine if user creden-
     tials should be set.

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

     PAM_CRED_UNAVAIL
           Underlying authentication  service  can  not  retrieve
           user credentials.

     PAM_CRED_EXPIRED
           User credentials have expired.

     PAM_USER_UNKNOWN
           User unknown to the authentication service.

     PAM_CRED_ERR
           Failure in setting user credentials.

     PAM_IGNORE
           Ignore underlying authentication module regardless  of
           whether  the  control  flag  is  required,optional, or
           sufficient.

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

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

SEE ALSO
     pam(3PAM),    pam_authenticate(3PAM),     pam_get_data(3PAM)
     pam_setcred(3PAM),  pam_sm_authenticate(3PAM), libpam(3LIB),
     pam.conf(4), attributes(5)

NOTES
     The pam_sm_setcred() function  is  passed  the  same  module
     options that are used by pam_sm_authenticate().

SunOS 5.8           Last change: 13 Oct 1998                    2

PAM Library Functions                        pam_sm_setcred(3PAM)

     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: 13 Oct 1998                    3