Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
PAM(3)		       FreeBSD Library Functions Manual			PAM(3)

NAME
     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

LIBRARY
     Pluggable Authentication Module Library (libpam, -lpam)

SYNOPSIS
     #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(pam_handle_t *pamh, const char *module_data_name,
	 void **data);

     int
     pam_get_item(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(pam_handle_t *pamh, int error_number);

DESCRIPTION
     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.

   Terminology
     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.

   Conversation
     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
     details.

   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-
     tion.

   Storage
     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.

   Authentication
     There are two authentication primitives: pam_authenticate() and
     pam_setcred().  The former	authenticates the user,	while the latter man-
     ages his credentials.

   Account Management
     The pam_acct_mgmt() function enforces policies such as password expiry,
     account expiry, time-of-day restrictions, and so forth.

   Session Management
     The pam_open_session() and	pam_close_session() functions handle session
     setup and teardown.

   Password Management
     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.

   Miscellaneous
     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.

RETURN VALUES
     The following return codes	are defined by <security/pam_constants.h>:

     [PAM_ABORT]	 General failure.

     [PAM_ACCT_EXPIRED]	 User account has expired.

     [PAM_AUTHINFO_UNAVAIL]
			 Authentication	information is unavailable.

     [PAM_AUTHTOK_DISABLE_AGING]
			 Authentication	token aging disabled.

     [PAM_AUTHTOK_ERR]	 Authentication	token failure.

     [PAM_AUTHTOK_EXPIRED]
			 Password has expired.

     [PAM_AUTHTOK_LOCK_BUSY]
			 Authentication	token lock busy.

     [PAM_AUTHTOK_RECOVERY_ERR]
			 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_INSUFFICIENT]
			 Insufficient credentials.

     [PAM_CRED_UNAVAIL]	 Failed	to retrieve user credentials.

     [PAM_DOMAIN_UNKNOWN]
			 Unknown authentication	domain.

     [PAM_IGNORE]	 Ignore	this module.

     [PAM_MAXTRIES]	 Maximum number	of tries exceeded.

     [PAM_MODULE_UNKNOWN]
			 Unknown module	type.

     [PAM_NEW_AUTHTOK_REQD]
			 New authentication token required.

     [PAM_NO_MODULE_DATA]
			 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_SUCCESS]	 Success.

     [PAM_SYMBOL_ERR]	 Invalid symbol.

     [PAM_SYSTEM_ERR]	 System	error.

     [PAM_TRY_AGAIN]	 Try again.

     [PAM_USER_UNKNOWN]	 Unknown user.

SEE ALSO
     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)

STANDARDS
     X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules,
     June 1997.

AUTHORS
     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-
     gram.

FreeBSD	6.0			 June 16, 2005			   FreeBSD 6.0

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUES | SEE ALSO | STANDARDS | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pam&sektion=3&manpath=FreeBSD+6.0-RELEASE>

home | help