PAM_AUTHENTICATE(3PAM) PAM Library Functions PAM_AUTHENTICATE(3PAM)

NAME

pam_authenticate - perform authentication within the PAM framework

SYNOPSIS

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


int pam_authenticate(pam_handle_t *pamh, int flags);

DESCRIPTION

The pam_authenticate() function 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. 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
Authentication service should not
generate any messages.


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

RETURN VALUES

Upon successful completion, PAM_SUCCESS is returned. In addition to
the error return values described in pam(3PAM), the following values
may be returned:

PAM_AUTH_ERR
Authentication failure.


PAM_CRED_INSUFFICIENT
Cannot access authentication data due to
insufficient credentials.


PAM_AUTHINFO_UNAVAIL
Underlying authentication service cannot
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.

ATTRIBUTES

See attributes(7) for description of the following attributes:


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

SEE ALSO

libpam(3LIB), pam(3PAM), pam_open_session(3PAM), pam_set_item(3PAM),
pam_setcred(3PAM), pam_start(3PAM), attributes(7)

NOTES

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 cannot load the authentication module, then it
will return PAM_ABORT. This indicates a serious failure, and 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 each of 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 be no prompt to the user to
enter an authentication token.


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

January 27, 2005 PAM_AUTHENTICATE(3PAM)