hpux man page for pam_authenticate

pam_authenticate(3)					     Library Functions Manual					       pam_authenticate(3)

NAME
       pam_authenticate - perform authentication within the PAM framework

SYNOPSIS
       [ flag ... ] file ...  [ library ... ]

DESCRIPTION
       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  (Personal
       Identification  Number).  The user in question should have been specified by a prior call to or The following flags may be set in the flags
       field:

	      Authentication service should not generate any messages

	      The authentication service should return
		     if the user has a null authentication token

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

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

       If the PAM framework can not load the authentication module, then it will return 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, requires that the user re-authenticate to all the services.

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

       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
       Upon successful completion, is returned.  In addition to the error return values described in pam(3), the following values may be returned:

       Authentication failure.

       Can not access authentication data due to insufficient credentials.

       Underlying authentication service can not retrieve authentication information.

       User not known to the underlying authentication module.

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

SEE ALSO
       pam(3), pam_start(3), pam_open_session(3), pam_setcred(3).

															       pam_authenticate(3)