NAME

pam_authenticate - perform authentication within the PAM framework

SYNOPSIS

#include <security/pam_appl.h>

int pam_authenticate (
    pam_handle_t    *pamh,
    int              flags
);

DESCRIPTION

The pam_authenticate() function is called to authenticate a 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 may have been specified by a prior call to pam_start() or pam_set_item(). The underlying PAM modules may use the PAM conversation functions to get information about the user.

In the case of an authentication failure due to an incorrect username or password as denoted by the error code [PAM_AUTH_ERR] or [PAM_USER_UNKNOWN], 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_OPEN_ERR].

For security reasons, the location of the authentication failure 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.

For security reasons, pam_authenticate() clears the PAM_AUTHTOK item in the PAM handle prior to returning to the application.

The arguments for pam_authenticate() are:

pamh (in)

The PAM authentication handle, returned from a previous call to pam_start().

flags (in)

Flags which determine the actions to be taken on authentication. These may be set to:

PAM_SILENT
The authentication service shall not display any messages.

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

RETURN VALUE

One of the following PAM status codes shall be returned:

[PAM_SUCCESS]

Successful completion.

[PAM_AUTH_ERR]

There has been an error in authenticating the user. This occurs if the user submits an invalid authentication token, or if the PAM_DISALLOW_NULL_AUTHTOK flag is set and the user submits a NULL authentication token.

[PAM_CRED_INSUFFICIENT]

Cannot access authentication data due to insufficient credentials.

[PAM_AUTHINFO_UNAVAIL]

The underlying authentication service cannot retrieve the authentication information.

[PAM_USER_UNKNOWN]

The user is not known to the authentication module.

[PAM_MAXTRIES]

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

[PAM_OPEN_ERR]

Failure when dynamically loading one of the authentication service modules.

[PAM_SYMBOL_ERR]

Symbol not found in service module.

[PAM_SERVICE_ERR]

Error in service module.

[PAM_SYSTEM_ERR]

System error.

[PAM_BUF_ERR]

Memory buffer error.

[PAM_CONV_ERR]

Conversation error.

[PAM_PERM_DENIED]

Permission denied.

[??] Some characters or strings that appear in the printed document are not easily representable using HTML.