Attempts to authenticate a user through PAM.
PAM Library (libpam.a)
#include <security/pam_appl.h>
int pam_authenticate (PAMHandle, Flags)
pam_handle_t *PAMHandle;
int Flags;
The pam_authenticate subroutine authenticates a user through PAM. The authentication method used is determined by the authentication modules configured in the /etc/pam.conf stack. Most authentication requires a password or other user input but is dependent on the modules in use.
Before attempting authentication through pam_authenticate, ensure that all of the applicable PAM information has been set through the initial call to pam_start() and subsequent calls to pam_set_item(). If any necessary information is not set, PAM modules can prompt the user for information through the routine defined in PAM_CONV. If required information is not provided and PAM_CONV is not set, the authentication fails.
On failure, it is the responsibility of the calling application to maintain a count of authentication attempts and to reinvoke the subroutine if the count has not exceeded a defined limit. Some authentication modules maintain an internal count and return PAM_MAXTRIES if the limit is reached. After the stack of authentication modules has finished with either success or failure, PAM_AUTHTOK is cleared in the handle.
| Item | Description |
|---|---|
| PAMhandle | The PAM handle representing the current user authentication session. This handle is obtained by a call to pam_start(). |
| Flags | The Flags argument can be a logically OR'd combination
of the following:
|
Upon successful completion, pam_authenticate returns PAM_SUCCESS. If the routine fails, a different error will be returned, depending on the actual error.
| Item | Description |
|---|---|
| PAM_AUTH_ERR | An error occurred in authentication, usually because of an invalid authentication token. |
| PAM_CRED_INSUFFICIENT | The user has insufficient credentials to access the authentication data. |
| PAM_AUTHINFO_UNAVAIL | The authentication information cannot be retrieved. |
| PAM_USER_UNKNOWN | The user is not known. |
| PAM_MAXTRIES | The maximum number of authentication retries has been reached. |
| PAM_OPEN_ERR | One of the PAM authentication modules could not be loaded. |
| PAM_SYMBOL_ERR | A necessary item is not available to a PAM module. |
| PAM_SERVICE_ERR | An error occurred in a PAM module. |
| PAM_SYSTEM_ERR | A system error occurred. |
| PAM_BUF_ERR | A memory error occurred. |
| PAM_CONV_ERR | A conversation error occurred. |
| PAM_PERM_DENIED | Access permission was denied to the user. |