PAM(3) | Library Functions Manual | PAM(3) |
pam_acct_mgmt
,
pam_authenticate
,
pam_chauthtok
,
pam_close_session
, pam_end
,
pam_get_data
, pam_get_item
,
pam_get_user
, pam_getenv
,
pam_getenvlist
,
pam_open_session
,
pam_putenv
, pam_set_data
,
pam_set_item
, pam_setcred
,
pam_start
, pam_strerror
— Pluggable Authentication Modules
Library
Pluggable Authentication Module Library (libpam, -lpam)
#include
<security/pam_appl.h>
int
pam_acct_mgmt
(pam_handle_t
*pamh, int
flags);
int
pam_authenticate
(pam_handle_t
*pamh, int
flags);
int
pam_chauthtok
(pam_handle_t
*pamh, int
flags);
int
pam_close_session
(pam_handle_t
*pamh, int
flags);
int
pam_end
(pam_handle_t
*pamh, int
status);
int
pam_get_data
(const
pam_handle_t *pamh, const
char *module_data_name,
const void **data);
int
pam_get_item
(const
pam_handle_t *pamh, int
item_type, const void
**item);
int
pam_get_user
(pam_handle_t
*pamh, const char
**user, const char
*prompt);
const char *
pam_getenv
(pam_handle_t
*pamh, const char
*name);
char **
pam_getenvlist
(pam_handle_t
*pamh);
int
pam_open_session
(pam_handle_t
*pamh, int
flags);
int
pam_putenv
(pam_handle_t
*pamh, const char
*namevalue);
int
pam_set_data
(pam_handle_t
*pamh, const char
*module_data_name, void
*data, void
(*cleanup)(pam_handle_t *pamh, void *data, int pam_end_status));
int
pam_set_item
(pam_handle_t
*pamh, int
item_type, const void
*item);
int
pam_setcred
(pam_handle_t
*pamh, int
flags);
int
pam_start
(const
char *service, const char
*user, const struct
pam_conv *pam_conv,
pam_handle_t **pamh);
const char *
pam_strerror
(const
pam_handle_t *pamh, int
error_number);
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 ways.
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 management and password management.
The PAM library expects the application to provide a conversation callback 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 details.
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 handle, so it is
possible to conduct multiple transactions in parallel.
The
pam_end
()
function releases all resources associated with the specified context, and
can be called at any time to terminate a PAM transaction.
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 invocation to another.
There are two authentication primitives:
pam_authenticate
()
and
pam_setcred
().
The former authenticates the user, while the latter manages 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 password, 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
]PAM_ACCT_EXPIRED
]PAM_APPLE_ACCT_TEMP_LOCK
]PAM_APPLE_ACCT_LOCKED
]PAM_AUTHINFO_UNAVAIL
]PAM_AUTHTOK_DISABLE_AGING
]PAM_AUTHTOK_ERR
]PAM_AUTHTOK_EXPIRED
]PAM_AUTHTOK_LOCK_BUSY
]PAM_AUTHTOK_RECOVERY_ERR
]PAM_AUTH_ERR
]PAM_BUF_ERR
]PAM_CONV_ERR
]PAM_CRED_ERR
]PAM_CRED_EXPIRED
]PAM_CRED_INSUFFICIENT
]PAM_CRED_UNAVAIL
]PAM_DOMAIN_UNKNOWN
]PAM_IGNORE
]PAM_MAXTRIES
]PAM_MODULE_UNKNOWN
]PAM_NEW_AUTHTOK_REQD
]PAM_NO_MODULE_DATA
]PAM_OPEN_ERR
]PAM_PERM_DENIED
]PAM_SERVICE_ERR
]PAM_SESSION_ERR
]PAM_SUCCESS
]PAM_SYMBOL_ERR
]PAM_SYSTEM_ERR
]PAM_TRY_AGAIN
]PAM_USER_UNKNOWN
]openpam(3), pam_acct_mgmt(3), pam_authenticate(3), pam_chauthtok(3), pam_close_session(3), pam_conv(3), pam_end(3), pam_get_data(3), pam_getenv(3), pam_getenvlist(3), pam_get_item(3), pam_get_user(3), pam_open_session(3), pam_putenv(3), pam_setcred(3), pam_set_data(3), pam_set_item(3), pam_start(3), pam_strerror(3)
X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules, June 1997.
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 program.
December 21, 2007 | macOS 14.6 |