pam_authenticate Subroutine

Edit online

Purpose

Attempts to authenticate a user through PAM.

Library

PAM Library (libpam.a)

Syntax

#include <security/pam_appl.h>

int pam_authenticate (PAMHandle, Flags)
pam_handle_t *PAMHandle;
int Flags;

Description

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.

Parameters

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:
  • PAM_SILENT
    • No messages should be displayed
  • PAM_DISALLOW_NULL_AUTHTOK
    • Do not authenticate a user with a NULL authentication token.

Return Values

Upon successful completion, pam_authenticate returns PAM_SUCCESS. If the routine fails, a different error will be returned, depending on the actual error.

Error Codes

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.