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