diff options
Diffstat (limited to 'doc/man/pam.3')
| -rw-r--r-- | doc/man/pam.3 | 293 |
1 files changed, 293 insertions, 0 deletions
diff --git a/doc/man/pam.3 b/doc/man/pam.3 new file mode 100644 index 0000000..5740a4d --- /dev/null +++ b/doc/man/pam.3 @@ -0,0 +1,293 @@ +.\"- +.\" Copyright (c) 2001-2003 Networks Associates Technology, Inc. +.\" Copyright (c) 2004-2007 Dag-Erling Smørgrav +.\" All rights reserved. +.\" +.\" This software was 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. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $P4$ +.\" +.Dd December 21, 2007 +.Dt PAM 3 +.Os +.Sh NAME +.Nm pam_acct_mgmt , +.Nm pam_authenticate , +.Nm pam_chauthtok , +.Nm pam_close_session , +.Nm pam_end , +.Nm pam_get_data , +.Nm pam_get_item , +.Nm pam_get_user , +.Nm pam_getenv , +.Nm pam_getenvlist , +.Nm pam_open_session , +.Nm pam_putenv , +.Nm pam_set_data , +.Nm pam_set_item , +.Nm pam_setcred , +.Nm pam_start , +.Nm pam_strerror +.Nd Pluggable Authentication Modules Library +.Sh LIBRARY +.Lb libpam +.Sh SYNOPSIS +.In security/pam_appl.h +.Ft "int" +.Fn pam_acct_mgmt "pam_handle_t *pamh" "int flags" +.Ft "int" +.Fn pam_authenticate "pam_handle_t *pamh" "int flags" +.Ft "int" +.Fn pam_chauthtok "pam_handle_t *pamh" "int flags" +.Ft "int" +.Fn pam_close_session "pam_handle_t *pamh" "int flags" +.Ft "int" +.Fn pam_end "pam_handle_t *pamh" "int status" +.Ft "int" +.Fn pam_get_data "const pam_handle_t *pamh" "const char *module_data_name" "const void **data" +.Ft "int" +.Fn pam_get_item "const pam_handle_t *pamh" "int item_type" "const void **item" +.Ft "int" +.Fn pam_get_user "pam_handle_t *pamh" "const char **user" "const char *prompt" +.Ft "const char *" +.Fn pam_getenv "pam_handle_t *pamh" "const char *name" +.Ft "char **" +.Fn pam_getenvlist "pam_handle_t *pamh" +.Ft "int" +.Fn pam_open_session "pam_handle_t *pamh" "int flags" +.Ft "int" +.Fn pam_putenv "pam_handle_t *pamh" "const char *namevalue" +.Ft "int" +.Fn 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)" +.Ft "int" +.Fn pam_set_item "pam_handle_t *pamh" "int item_type" "const void *item" +.Ft "int" +.Fn pam_setcred "pam_handle_t *pamh" "int flags" +.Ft "int" +.Fn pam_start "const char *service" "const char *user" "const struct pam_conv *pam_conv" "pam_handle_t **pamh" +.Ft "const char *" +.Fn pam_strerror "const pam_handle_t *pamh" "int error_number" +.\" +.\" $Id: pam.man 320 2006-02-16 20:33:19Z des $ +.\" +.Sh 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. +.Ss 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. +.Pp +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. +.Pp +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. +.Pp +The functionality embodied by PAM is divided into six primitives +grouped into four facilities: authentication, account management, +session management and password management. +.Ss Conversation +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 +.Xr pam_conv 3 +for details. +.Ss Initialization and Cleanup +The +.Fn 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. +.Pp +The +.Fn pam_end +function releases all resources associated with the specified context, +and can be called at any time to terminate a PAM transaction. +.Ss Storage +The +.Fn pam_set_item +and +.Fn 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. +.Pp +The +.Fn pam_set_data +and +.Fn pam_get_data +functions manage named chunks of free-form data, generally used by +modules to store state from one invocation to another. +.Ss Authentication +There are two authentication primitives: +.Fn pam_authenticate +and +.Fn pam_setcred . +The former authenticates the user, while the latter manages his +credentials. +.Ss Account Management +The +.Fn pam_acct_mgmt +function enforces policies such as password expiry, account expiry, +time-of-day restrictions, and so forth. +.Ss Session Management +The +.Fn pam_open_session +and +.Fn pam_close_session +functions handle session setup and teardown. +.Ss Password Management +The +.Fn pam_chauthtok +function allows the server to change the user's password, either at +the user's request or because the password has expired. +.Ss Miscellaneous +The +.Fn pam_putenv , +.Fn pam_getenv +and +.Fn pam_getenvlist +functions manage a private environment list in which modules can set +environment variables they want the server to export during the +session. +.Pp +The +.Fn pam_strerror +function returns a pointer to a string describing the specified PAM +error code. +.Sh RETURN VALUES +The following return codes are defined by +.In security/pam_constants.h : +.Bl -tag -width 18n +.It Bq Er PAM_ABORT +General failure. +.It Bq Er PAM_ACCT_EXPIRED +User account has expired. +.It Bq Er PAM_AUTHINFO_UNAVAIL +Authentication information is unavailable. +.It Bq Er PAM_AUTHTOK_DISABLE_AGING +Authentication token aging disabled. +.It Bq Er PAM_AUTHTOK_ERR +Authentication token failure. +.It Bq Er PAM_AUTHTOK_EXPIRED +Password has expired. +.It Bq Er PAM_AUTHTOK_LOCK_BUSY +Authentication token lock busy. +.It Bq Er PAM_AUTHTOK_RECOVERY_ERR +Failed to recover old authentication token. +.It Bq Er PAM_AUTH_ERR +Authentication error. +.It Bq Er PAM_BUF_ERR +Memory buffer error. +.It Bq Er PAM_CONV_ERR +Conversation failure. +.It Bq Er PAM_CRED_ERR +Failed to set user credentials. +.It Bq Er PAM_CRED_EXPIRED +User credentials have expired. +.It Bq Er PAM_CRED_INSUFFICIENT +Insufficient credentials. +.It Bq Er PAM_CRED_UNAVAIL +Failed to retrieve user credentials. +.It Bq Er PAM_DOMAIN_UNKNOWN +Unknown authentication domain. +.It Bq Er PAM_IGNORE +Ignore this module. +.It Bq Er PAM_MAXTRIES +Maximum number of tries exceeded. +.It Bq Er PAM_MODULE_UNKNOWN +Unknown module type. +.It Bq Er PAM_NEW_AUTHTOK_REQD +New authentication token required. +.It Bq Er PAM_NO_MODULE_DATA +Module data not found. +.It Bq Er PAM_OPEN_ERR +Failed to load module. +.It Bq Er PAM_PERM_DENIED +Permission denied. +.It Bq Er PAM_SERVICE_ERR +Error in service module. +.It Bq Er PAM_SESSION_ERR +Session failure. +.It Bq Er PAM_SUCCESS +Success. +.It Bq Er PAM_SYMBOL_ERR +Invalid symbol. +.It Bq Er PAM_SYSTEM_ERR +System error. +.It Bq Er PAM_TRY_AGAIN +Try again. +.It Bq Er PAM_USER_UNKNOWN +Unknown user. +.El +.Sh SEE ALSO +.Xr openpam 3 , +.Xr pam_acct_mgmt 3 , +.Xr pam_authenticate 3 , +.Xr pam_chauthtok 3 , +.Xr pam_close_session 3 , +.Xr pam_conv 3 , +.Xr pam_end 3 , +.Xr pam_get_data 3 , +.Xr pam_getenv 3 , +.Xr pam_getenvlist 3 , +.Xr pam_get_item 3 , +.Xr pam_get_user 3 , +.Xr pam_open_session 3 , +.Xr pam_putenv 3 , +.Xr pam_setcred 3 , +.Xr pam_set_data 3 , +.Xr pam_set_item 3 , +.Xr pam_start 3 , +.Xr pam_strerror 3 +.Sh STANDARDS +.Rs +.%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules" +.%D "June 1997" +.Re +.Sh AUTHORS +The OpenPAM library and this manual page were developed for the +.Fx +Project by ThinkSec AS and Network Associates Laboratories, the +Security Research Division of Network Associates, Inc.\& under +DARPA/SPAWAR contract N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. |
