- NetBSD Manual Pages
PAM(3) NetBSD Library Functions Manual PAM(3)
Powered by man-cgi (2021-06-01).
Maintained for NetBSD
by Kimmo Suominen.
Based on man-cgi by Panagiotis Christias.
pam -- Pluggable Authentication Modules Library
Pluggable Authentication Module Library (libpam, -lpam)
The Pluggable Authentication Modules (PAM) library abstracts a number of
common authentication-related operations and provides a framework for
dynamically loaded modules that implement these operations in various
In PAM parlance, the application that uses PAM to authenticate a user is
the server, and is identified for configuration purposes by a service
name, which is often (but not necessarily) the program name.
The user requesting authentication is called the applicant, while the
user (usually, root) charged with verifying his identity and granting him
the requested credentials is called the arbitrator.
The sequence of operations the server goes through to authenticate a user
and perform whatever task he requested is a PAM transaction; the context
within which the server performs the requested task is called a session.
The functionality embodied by PAM is divided into six primitives grouped
into four facilities: authentication, account management, session manage-
ment and password management.
The PAM library expects the application to provide a conversation call-
back which it can use to communicate with the user. Some modules may use
specialized conversation functions to communicate with special hardware
such as cryptographic dongles or biometric devices. See pam_conv(3) for
Initialization and Cleanup
The pam_start() function initializes the PAM library and returns a handle
which must be provided in all subsequent function calls. The transaction
state is contained entirely within the structure identified by this han-
dle, so it is possible to conduct multiple transactions in parallel.
The pam_end() function releases all resources associated with the speci-
fied context, and can be called at any time to terminate a PAM transac-
The pam_set_item() and pam_get_item() functions set and retrieve a number
of predefined items, including the service name, the names of the
requesting and target users, the conversation function, and prompts.
The pam_set_data() and pam_get_data() functions manage named chunks of
free-form data, generally used by modules to store state from one invoca-
tion to another.
There are two authentication primitives: pam_authenticate() and
pam_setcred(). The former authenticates the user, while the latter man-
ages his credentials.
The pam_acct_mgmt() function enforces policies such as password expiry,
account expiry, time-of-day restrictions, and so forth.
The pam_open_session() and pam_close_session() functions handle session
setup and teardown.
The pam_chauthtok() function allows the server to change the user's pass-
word, either at the user's request or because the password has expired.
The pam_putenv(), pam_getenv() and pam_getenvlist() functions manage a
private environment list in which modules can set environment variables
they want the server to export during the session.
The pam_strerror() function returns a pointer to a string describing the
specified PAM error code.
The following return codes are defined by <security/pam_constants.h>:
[PAM_ABORT] General failure.
[PAM_ACCT_EXPIRED] User account has expired.
Authentication information is unavailable.
Authentication token aging disabled.
[PAM_AUTHTOK_ERR] Authentication token failure.
Password has expired.
Authentication token lock busy.
Failed to recover old authentication token.
[PAM_AUTH_ERR] Authentication error.
[PAM_BUF_ERR] Memory buffer error.
[PAM_CONV_ERR] Conversation failure.
[PAM_CRED_ERR] Failed to set user credentials.
[PAM_CRED_EXPIRED] User credentials have expired.
[PAM_CRED_UNAVAIL] Failed to retrieve user credentials.
Unknown authentication domain.
[PAM_IGNORE] Ignore this module.
[PAM_MAXTRIES] Maximum number of tries exceeded.
Unknown module type.
New authentication token required.
Module data not found.
[PAM_OPEN_ERR] Failed to load module.
[PAM_PERM_DENIED] Permission denied.
[PAM_SERVICE_ERR] Error in service module.
[PAM_SESSION_ERR] Session failure.
[PAM_SYMBOL_ERR] Invalid symbol.
[PAM_SYSTEM_ERR] System error.
[PAM_TRY_AGAIN] Try again.
[PAM_USER_UNKNOWN] Unknown user.
X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules,
The OpenPAM library and this manual page were developed for the FreeBSD
Project by ThinkSec AS and Network Associates Laboratories, the Security
Research Division of Network Associates, Inc. under DARPA/SPAWAR contract
N66001-01-C-8035 (``CBOSS''), as part of the DARPA CHATS research pro-
The OpenPAM library is maintained by Dag-Erling Smørgrav <email@example.com>.
NetBSD 7.1.2 September 12, 2014 NetBSD 7.1.2