1.\"- 2.\" Copyright (c) 2001-2003 Networks Associates Technology, Inc. 3.\" All rights reserved. 4.\" 5.\" This software was developed for the FreeBSD Project by ThinkSec AS and 6.\" Network Associates Laboratories, the Security Research Division of 7.\" Network Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 8.\" ("CBOSS"), as part of the DARPA CHATS research program. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 3. The name of the author may not be used to endorse or promote 19.\" products derived from this software without specific prior written 20.\" permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" $P4$ 35.\" 36.Dd June 16, 2005 37.Dt PAM 3 38.Os 39.Sh NAME 40.Nm pam_acct_mgmt , 41.Nm pam_authenticate , 42.Nm pam_chauthtok , 43.Nm pam_close_session , 44.Nm pam_end , 45.Nm pam_get_data , 46.Nm pam_get_item , 47.Nm pam_get_user , 48.Nm pam_getenv , 49.Nm pam_getenvlist , 50.Nm pam_open_session , 51.Nm pam_putenv , 52.Nm pam_set_data , 53.Nm pam_set_item , 54.Nm pam_setcred , 55.Nm pam_start , 56.Nm pam_strerror 57.Nd Pluggable Authentication Modules Library 58.Sh LIBRARY 59.Lb libpam 60.Sh SYNOPSIS 61.In security/pam_appl.h 62.Ft "int" 63.Fn pam_acct_mgmt "pam_handle_t *pamh" "int flags" 64.Ft "int" 65.Fn pam_authenticate "pam_handle_t *pamh" "int flags" 66.Ft "int" 67.Fn pam_chauthtok "pam_handle_t *pamh" "int flags" 68.Ft "int" 69.Fn pam_close_session "pam_handle_t *pamh" "int flags" 70.Ft "int" 71.Fn pam_end "pam_handle_t *pamh" "int status" 72.Ft "int" 73.Fn pam_get_data "pam_handle_t *pamh" "const char *module_data_name" "void **data" 74.Ft "int" 75.Fn pam_get_item "pam_handle_t *pamh" "int item_type" "const void **item" 76.Ft "int" 77.Fn pam_get_user "pam_handle_t *pamh" "const char **user" "const char *prompt" 78.Ft "const char *" 79.Fn pam_getenv "pam_handle_t *pamh" "const char *name" 80.Ft "char **" 81.Fn pam_getenvlist "pam_handle_t *pamh" 82.Ft "int" 83.Fn pam_open_session "pam_handle_t *pamh" "int flags" 84.Ft "int" 85.Fn pam_putenv "pam_handle_t *pamh" "const char *namevalue" 86.Ft "int" 87.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)" 88.Ft "int" 89.Fn pam_set_item "pam_handle_t *pamh" "int item_type" "const void *item" 90.Ft "int" 91.Fn pam_setcred "pam_handle_t *pamh" "int flags" 92.Ft "int" 93.Fn pam_start "const char *service" "const char *user" "const struct pam_conv *pam_conv" "pam_handle_t **pamh" 94.Ft "const char *" 95.Fn pam_strerror "pam_handle_t *pamh" "int error_number" 96.\" 97.\" $P4: //depot/projects/openpam/doc/man/pam.man#4 $ 98.\" 99.Sh DESCRIPTION 100The Pluggable Authentication Modules (PAM) library abstracts a number 101of common authentication-related operations and provides a framework 102for dynamically loaded modules that implement these operations in 103various ways. 104.Ss Terminology 105In PAM parlance, the application that uses PAM to authenticate a user 106is the server, and is identified for configuration purposes by a 107service name, which is often (but not necessarily) the program name. 108.Pp 109The user requesting authentication is called the applicant, while the 110user (usually, root) charged with verifying his identity and granting 111him the requested credentials is called the arbitrator. 112.Pp 113The sequence of operations the server goes through to authenticate a 114user and perform whatever task he requested is a PAM transaction; the 115context within which the server performs the requested task is called 116a session. 117.Pp 118The functionality embodied by PAM is divided into six primitives 119grouped into four facilities: authentication, account management, 120session management and password management. 121.Ss Conversation 122The PAM library expects the application to provide a conversation 123callback which it can use to communicate with the user. 124Some modules may use specialized conversation functions to communicate 125with special hardware such as cryptographic dongles or biometric 126devices. 127See 128.Xr pam_conv 3 129for details. 130.Ss Initialization and Cleanup 131The 132.Fn pam_start 133function initializes the PAM library and returns a handle which must 134be provided in all subsequent function calls. 135The transaction state is contained entirely within the structure 136identified by this handle, so it is possible to conduct multiple 137transactions in parallel. 138.Pp 139The 140.Fn pam_end 141function releases all resources associated with the specified context, 142and can be called at any time to terminate a PAM transaction. 143.Ss Storage 144The 145.Fn pam_set_item 146and 147.Fn pam_get_item 148functions set and retrieve a number of predefined items, including the 149service name, the names of the requesting and target users, the 150conversation function, and prompts. 151.Pp 152The 153.Fn pam_set_data 154and 155.Fn pam_get_data 156functions manage named chunks of free-form data, generally used by 157modules to store state from one invocation to another. 158.Ss Authentication 159There are two authentication primitives: 160.Fn pam_authenticate 161and 162.Fn pam_setcred . 163The former authenticates the user, while the latter manages his 164credentials. 165.Ss Account Management 166The 167.Fn pam_acct_mgmt 168function enforces policies such as password expiry, account expiry, 169time-of-day restrictions, and so forth. 170.Ss Session Management 171The 172.Fn pam_open_session 173and 174.Fn pam_close_session 175functions handle session setup and teardown. 176.Ss Password Management 177The 178.Fn pam_chauthtok 179function allows the server to change the user's password, either at 180the user's request or because the password has expired. 181.Ss Miscellaneous 182The 183.Fn pam_putenv , 184.Fn pam_getenv 185and 186.Fn pam_getenvlist 187functions manage a private environment list in which modules can set 188environment variables they want the server to export during the 189session. 190.Pp 191The 192.Fn pam_strerror 193function returns a pointer to a string describing the specified PAM 194error code. 195.Sh RETURN VALUES 196The following return codes are defined by 197.In security/pam_constants.h : 198.Bl -tag -width 18n 199.It Bq Er PAM_ABORT 200General failure. 201.It Bq Er PAM_ACCT_EXPIRED 202User account has expired. 203.It Bq Er PAM_AUTHINFO_UNAVAIL 204Authentication information is unavailable. 205.It Bq Er PAM_AUTHTOK_DISABLE_AGING 206Authentication token aging disabled. 207.It Bq Er PAM_AUTHTOK_ERR 208Authentication token failure. 209.It Bq Er PAM_AUTHTOK_EXPIRED 210Password has expired. 211.It Bq Er PAM_AUTHTOK_LOCK_BUSY 212Authentication token lock busy. 213.It Bq Er PAM_AUTHTOK_RECOVERY_ERR 214Failed to recover old authentication token. 215.It Bq Er PAM_AUTH_ERR 216Authentication error. 217.It Bq Er PAM_BUF_ERR 218Memory buffer error. 219.It Bq Er PAM_CONV_ERR 220Conversation failure. 221.It Bq Er PAM_CRED_ERR 222Failed to set user credentials. 223.It Bq Er PAM_CRED_EXPIRED 224User credentials have expired. 225.It Bq Er PAM_CRED_INSUFFICIENT 226Insufficient credentials. 227.It Bq Er PAM_CRED_UNAVAIL 228Failed to retrieve user credentials. 229.It Bq Er PAM_DOMAIN_UNKNOWN 230Unknown authentication domain. 231.It Bq Er PAM_IGNORE 232Ignore this module. 233.It Bq Er PAM_MAXTRIES 234Maximum number of tries exceeded. 235.It Bq Er PAM_MODULE_UNKNOWN 236Unknown module type. 237.It Bq Er PAM_NEW_AUTHTOK_REQD 238New authentication token required. 239.It Bq Er PAM_NO_MODULE_DATA 240Module data not found. 241.It Bq Er PAM_OPEN_ERR 242Failed to load module. 243.It Bq Er PAM_PERM_DENIED 244Permission denied. 245.It Bq Er PAM_SERVICE_ERR 246Error in service module. 247.It Bq Er PAM_SESSION_ERR 248Session failure. 249.It Bq Er PAM_SUCCESS 250Success. 251.It Bq Er PAM_SYMBOL_ERR 252Invalid symbol. 253.It Bq Er PAM_SYSTEM_ERR 254System error. 255.It Bq Er PAM_TRY_AGAIN 256Try again. 257.It Bq Er PAM_USER_UNKNOWN 258Unknown user. 259.El 260.Sh SEE ALSO 261.Xr openpam 3 , 262.Xr pam_acct_mgmt 3 , 263.Xr pam_authenticate 3 , 264.Xr pam_chauthtok 3 , 265.Xr pam_close_session 3 , 266.Xr pam_conv 3 , 267.Xr pam_end 3 , 268.Xr pam_get_data 3 , 269.Xr pam_getenv 3 , 270.Xr pam_getenvlist 3 , 271.Xr pam_get_item 3 , 272.Xr pam_get_user 3 , 273.Xr pam_open_session 3 , 274.Xr pam_putenv 3 , 275.Xr pam_setcred 3 , 276.Xr pam_set_data 3 , 277.Xr pam_set_item 3 , 278.Xr pam_start 3 , 279.Xr pam_strerror 3 280.Sh STANDARDS 281.Rs 282.%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules" 283.%D "June 1997" 284.Re 285.Sh AUTHORS 286The OpenPAM library and this manual page were developed for the 287.Fx 288Project by ThinkSec AS and Network Associates Laboratories, the 289Security Research Division of Network Associates, Inc.\& under 290DARPA/SPAWAR contract N66001-01-C-8035 291.Pq Dq CBOSS , 292as part of the DARPA CHATS research program. 293