pam_authenticate(3)                                     pam_authenticate(3)




 NAME    [Toc]    [Back]
      pam_authenticate - perform authentication within the PAM framework

 SYNOPSIS    [Toc]    [Back]
      cc [ flag ... ] file ...  -lpam [ library ... ]

      #include <security/pam_appl.h>

      int pam_authenticate(pam_handle_t *pamh, int flags);

 DESCRIPTION    [Toc]    [Back]
      pam_authenticate() is called to authenticate the current user.  The
      user is usually required to enter a password or similar authentication
      token depending upon the authentication service configured within the
      system. In the case of smart card authentication this token would be a
      PIN (Personal Identification Number).  The user in question should
      have been specified by a prior call to pam_start() or pam_set_item().
      The following flags may be set in the flags field:

           PAM_SILENT    [Toc]    [Back]
                Authentication service should not generate any messages

           PAM_DISALLOW_NULL_AUTHTOK    [Toc]    [Back]
                The authentication service should return PAM_AUTH_ERROR if
                the user has a null authentication token

 APPLICATION USAGE    [Toc]    [Back]
      Refer to pam(3) for information on thread-safety of PAM interfaces.

 NOTES    [Toc]    [Back]
      In the case of authentication failures due to an incorrect username or
      password, it is the responsibility of the application to retry
      pam_authenticate() and to maintain the retry count.  An authentication
      service module may implement an internal retry count and return an
      error PAM_MAXTRIES if the module does not want the application to
      retry.

      If the PAM framework can not load the authentication module, then it
      will return PAM_ABORT.  This indicates a serious failure and that the
      application should not attempt to retry the authentication.

      For security reasons, the location of authentication failures is
      hidden from the user.  Thus, if several authentication services are
      stacked and a single service fails, pam_authenticate() requires that
      the user re-authenticate to all the services.

      A null authentication token in the authentication database will result
      in successful authentication unless PAM_DISALLOW_NULL_AUTHTOK was
      specified.  In such cases, there will not be any prompting for the
      user to enter an authentication token.




 Hewlett-Packard Company            - 1 -   HP-UX 11i Version 2: August 2003






 pam_authenticate(3)                                     pam_authenticate(3)




      The authentication can be done through a smart card. In this case the
      user plugs their smart card in the smart card reader and is required
      to enter their smart card PIN.

 RETURN VALUES    [Toc]    [Back]
      Upon successful completion, PAM_SUCCESS is returned.  In addition to
      the error return values described in pam(3), the following values may
      be returned:

      PAM_AUTH_ERR                    Authentication failure.

      PAM_CRED_INSUFFICIENT           Can not access authentication data due
                                      to insufficient credentials.

      PAM_AUTHINFO_UNAVAIL            Underlying authentication service can
                                      not retrieve authentication
                                      information.

      PAM_USER_UNKNOWN                User not known to the underlying
                                      authentication module.

      PAM_MAXTRIES                    An authentication service has
                                      maintained a retry count which has
                                      been reached. No further retries
                                      should be attempted.

 SEE ALSO    [Toc]    [Back]
      pam(3), pam_start(3), pam_open_session(3), pam_setcred(3).


 Hewlett-Packard Company            - 2 -   HP-UX 11i Version 2: August 2003