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