1 '\" te 2 .\" Copyright (C) 2006, Sun Microsystems, Inc. All Rights Reserved. 3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. 4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. 5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] 6 .TH PAM.CONF 4 "Jun 19, 2006" 7 .SH NAME 8 pam.conf \- configuration file for pluggable authentication modules 9 .SH SYNOPSIS 10 .LP 11 .nf 12 \fB/etc/pam.conf\fR 13 .fi 14 15 .SH DESCRIPTION 16 .LP 17 \fBpam.conf\fR is the configuration file for the Pluggable Authentication 18 Module architecture, or \fBPAM\fR. A \fBPAM\fR module provides functionality 19 for one or more of four possible services: authentication, account management, 20 session management, and password management. 21 .sp 22 .ne 2 23 .na 24 \fBauthentication service module\fR 25 .ad 26 .sp .6 27 .RS 4n 28 Provides functionality to authenticate a user and set up user credentials. 29 .RE 30 31 .sp 32 .ne 2 33 .na 34 \fBaccount management module\fR 35 .ad 36 .sp .6 37 .RS 4n 38 Provides functionality to determine if the current user's account is valid. 39 This includes checking for password and account expiration, as well as 40 verifying access hour restrictions. 41 .RE 42 43 .sp 44 .ne 2 45 .na 46 \fBsession management module\fR 47 .ad 48 .sp .6 49 .RS 4n 50 Provides functionality to set up and terminate login sessions. 51 .RE 52 53 .sp 54 .ne 2 55 .na 56 \fBpassword management module\fR 57 .ad 58 .sp .6 59 .RS 4n 60 Provides functionality to change a user's authentication token or password. 61 .RE 62 63 .sp 64 .LP 65 Each of the four service modules can be implemented as a shared library object 66 which can be referenced in the \fBpam.conf\fR configuration file. 67 .SS "Simplified pam.conf Configuration File" 68 .LP 69 The \fBpam.conf\fR file contains a listing of services. Each service is paired 70 with a corresponding service module. When a service is requested, its 71 associated module is invoked. Each entry may be a maximum of 256 characters, 72 including the end of line, and has the following format: 73 .sp 74 .in +2 75 .nf 76 \fIservice_name module_type control_flag module_path options\fR 77 .fi 78 .in -2 79 .sp 80 81 .sp 82 .LP 83 The following is an example of a \fBpam.conf\fR configuration file with support 84 for authentication, account management, session management and password 85 management modules (See the \fBpam.conf\fR file that is shipped with your 86 system for the contents of this file): 87 .sp 88 .in +2 89 .nf 90 login auth requisite pam_authtok_get.so.1 91 login auth required pam_dhkeys.so.1 92 login auth required pam_unix_auth.so.1 93 login auth required pam_dial_auth.so.1 94 95 other account requisite pam_roles.so.1 96 other account required pam_unix_account.so.1 97 98 other session required pam_unix_session.so.1 99 100 other password required pam_dhkeys.so.1 101 other password requisite pam_authtok_get.so.1 102 other password requisite pam_authtok_check.so.1 103 other password required pam_authtok_store.so.1 104 .fi 105 .in -2 106 107 .sp 108 .LP 109 \fIservice_name\fR denotes the service (for example, \fBlogin\fR, 110 \fBdtlogin\fR, or \fBrlogin\fR). 111 .sp 112 .LP 113 The keyword, "\fBother\fR," indicates the module that all other applications 114 which have not been specified should use. The "\fBother\fR" keyword can also be 115 used if all services of the same \fImodule_type\fR have the same requirements. 116 .sp 117 .LP 118 In the example, since all of the services use the same session module, they 119 could have been replaced by a single \fBother\fR line. 120 .sp 121 .LP 122 \fImodule_type\fR denotes the service module type: authentication (\fBauth\fR), 123 account management (\fBaccount\fR), session management (\fBsession\fR), or 124 password management (\fBpassword\fR). 125 .sp 126 .LP 127 The \fIcontrol_flag\fR field determines the behavior of stacking. 128 .sp 129 .LP 130 The \fImodule_path\fR field specifies the relative pathname to a shared library 131 object, or an included \fBPAM\fR configuration file, which implements the 132 service functionality. If the pathname is not absolute, shared library objects 133 are assumed to be relative to \fB/usr/lib/security/$ISA/\fR, and included 134 \fBPAM\fR configuration files are assumed to be relative to 135 \fB/usr/lib/security/\fR. 136 .sp 137 .LP 138 The \fBISA\fR token is replaced by an implementation defined directory name 139 which defines the path relative to the calling program's instruction set 140 architecture. 141 .sp 142 .LP 143 The \fIoptions\fR field is used by the \fBPAM\fR framework layer to pass module 144 specific options to the modules. It is up to the module to parse and interpret 145 the options. 146 .sp 147 .LP 148 This field can be used by the modules to turn on debugging or to pass any 149 module specific parameters such as a \fBTIMEOUT\fR value. The options supported 150 by the modules are documented in their respective manual pages. 151 .SS "Integrating Multiple Authentication Services With Stacking" 152 .LP 153 When a \fIservice_name\fR of the same \fImodule_type\fR is defined more than 154 once, the service is said to be stacked. Each module referenced in the 155 \fImodule_path\fR for that service is then processed in the order that it 156 occurs in the configuration file. The \fIcontrol_flag\fR field specifies the 157 continuation and failure semantics of the modules, and can contain one of the 158 following values: 159 .sp 160 .ne 2 161 .na 162 \fB\fBbinding\fR\fR 163 .ad 164 .RS 14n 165 If the service module returns success and no preceding \fBrequired\fR modules 166 returned failures, immediately return success without calling any subsequent 167 modules. If a failure is returned, treat the failure as a \fBrequired\fR module 168 failure, and continue to process the \fBPAM\fR stack. 169 .RE 170 171 .sp 172 .ne 2 173 .na 174 \fB\fBinclude\fR\fR 175 .ad 176 .RS 14n 177 Process the lines from the \fBPAM\fR configuration file that is specified in 178 the \fImodule_path\fR at this point in the \fBPAM\fR stack. The ``\fBother\fR'' 179 keyword is used if the specified service_name is not found. 32 levels of 180 included \fBPAM\fR configuration files are supported. Any options are ignored. 181 .RE 182 183 .sp 184 .ne 2 185 .na 186 \fB\fBoptional\fR\fR 187 .ad 188 .RS 14n 189 If the service module returns success, record the success, and continue to 190 process the \fBPAM\fR stack. If a failure is returned, and it is the first 191 \fBoptional\fR module failure, save the failure code as an \fBoptional\fR 192 failure. Continue to process the \fBPAM\fR stack. 193 .RE 194 195 .sp 196 .ne 2 197 .na 198 \fB\fBrequired\fR\fR 199 .ad 200 .RS 14n 201 If the service module returns success, record the success, and continue to 202 process the \fBPAM\fR stack. If a failure is returned, and it is the first 203 \fBrequired\fR failure, save the failure code as a \fBrequired\fR failure. 204 Continue to process the \fBPAM\fR stack. 205 .RE 206 207 .sp 208 .ne 2 209 .na 210 \fB\fBrequisite\fR\fR 211 .ad 212 .RS 14n 213 If the service module returns success, record the success, and continue to 214 process the \fBPAM\fR stack. If a failure is returned, immediately return the 215 first non-optional failure value recorded without calling any subsequent 216 modules. That is, return this failure unless a previous required service module 217 failed. If a previous required service module failed, then return the first of 218 those values. 219 .RE 220 221 .sp 222 .ne 2 223 .na 224 \fB\fBsufficient\fR\fR 225 .ad 226 .RS 14n 227 If the service module return success and no preceding required modules returned 228 failures, immediately return success without calling any subsequent modules. If 229 a failure is returned, treat the failure as an optional module failure, and 230 continue to process the \fBPAM\fR stack. 231 .RE 232 233 .sp 234 .LP 235 If the \fBPAM\fR stack runs to completion, that is, neither a \fBrequisite\fR 236 module failed, nor a \fBbinding\fR or \fBsufficient\fR module success stops it, 237 success is returned if no required modules failed and at least one required, 238 requisite, optional module succeeded. If no module succeeded and a required or 239 binding module failed, the first of those errors is returned. If no required or 240 binding module failed and an optional module failed, the first of the option 241 module errors is returned. If no module in the stack succeeded or failed, that 242 is, all modules returned an ignore status, a default error based on module 243 type, for example, "User account expired," is returned. 244 .sp 245 .LP 246 All errors in \fBpam.conf\fR entries are logged to \fBsyslog\fR as 247 \fBLOG_AUTH\fR | \fBLOG_ERR\fR errors. The use of a service with an error noted 248 in the \fBpam.conf\fR entry for that service will fail. The system 249 administrator will need to correct the noted errors before that service may be 250 used. If no services are available or the \fBpam.conf\fR file is missing, the 251 system administrator may enter system maintenance mode to correct or restore 252 the file. 253 .sp 254 .LP 255 The following is a sample configuration file that stacks the \fBsu\fR, 256 \fBlogin\fR, and \fBrlogin\fR services. 257 .sp 258 .in +2 259 .nf 260 su auth required pam_inhouse.so.1 261 su auth requisite pam_authtok_get.so.1 262 su auth required pam_dhkeys.so.1 263 su auth required pam_unix_auth.so.1 264 265 login auth requisite pam_authtok_get.so.1 266 login auth required pam_dhkeys.so.1 267 login auth required pam_unix_auth.so.1 268 login auth required pam_dial_auth.so.1 269 login auth optional pam_inhouse.so.1 270 271 rlogin auth sufficient pam_rhosts_auth.so.1 272 rlogin auth requisite pam_authtok_get.so.1 273 rlogin auth required pam_dhkeys.so.1 274 rlogin auth required pam_unix_auth.so.1 275 .fi 276 .in -2 277 278 .sp 279 .LP 280 In the case of \fBsu\fR, the user is authenticated by the \fBinhouse\fR and 281 \fBauthtok_get\fR, \fBdhkeys\fR, and \fBunix_auth\fR authentication modules. 282 Because the \fBinhouse\fR and the other authentication modules are 283 \fBrequired\fR and \fBrequisite\fR, respectively, an error is returned back to 284 the application if any module fails. In addition, if the \fBrequisite\fR 285 authentication (\fBpam_authtok_get\fR authentication) fails, the other 286 authentication modules are never invoked, and the error is returned immediately 287 back to the application. 288 .sp 289 .LP 290 In the case of \fBlogin\fR, the \fBrequired\fR keyword for \fIcontrol_flag\fR 291 requires that the user be allowed to login only if the user is authenticated by 292 all the service modules. If \fBpam_unix_auth\fR authentication fails, control 293 continues to proceed down the stack, and the \fBinhouse\fR authentication 294 module is invoked. \fBinhouse\fR authentication is optional by virtue of the 295 optional keyword in the \fIcontrol_flag\fR field. The user can still log in 296 even if \fBinhouse\fR authentication fails, assuming the modules stacked above 297 succeeded. 298 .sp 299 .LP 300 In the case of \fBrlogin\fR, the \fBsufficient\fR keyword for 301 \fIcontrol_flag\fR specifies that if the \fBrhosts\fR authentication check 302 succeeds, then \fBPAM\fR should return success to \fBrlogin\fR and \fBrlogin\fR 303 should not prompt the user for a password. The other authentication modules, 304 which are in the stack, will only be invoked if the \fBrhosts\fR check fails. 305 This gives the system administrator the flexibility to determine if 306 \fBrhosts\fR alone is sufficient enough to authenticate a remote user. 307 .sp 308 .LP 309 Some modules return \fBPAM_IGNORE\fR in certain situations. In these cases the 310 \fBPAM\fR framework ignores the entire entry in \fBpam.conf\fR regardless of 311 whether or not it is \fBbinding\fR, \fBrequisite\fR, \fBrequired\fR, 312 \fBoptional\fR, or \fBsufficient\fR. 313 .SS "Utilities and Files" 314 .LP 315 The specific service names and module types for each service should be 316 documented in the man page for that service. For instance, the \fBsshd\fR(1M) 317 man page lists all of the \fBPAM\fR service names and module types for the 318 \fBsshd\fR command. 319 .sp 320 .LP 321 The \fBPAM\fR configuration file does not dictate either the name or the 322 location of the service specific modules. The convention, however, is the 323 following: 324 .sp 325 .ne 2 326 .na 327 \fB\fBpam_module_name.so.x\fR\fR 328 .ad 329 .RS 29n 330 File that implements various function of specific authentication services. As 331 the relative pathname specified, \fB/usr/lib/security/$ISA\fR is prepended to 332 it. 333 .RE 334 335 .sp 336 .ne 2 337 .na 338 \fB\fB/etc/pam.conf\fR\fR 339 .ad 340 .RS 29n 341 Configuration file 342 .RE 343 344 .sp 345 .ne 2 346 .na 347 \fB\fB/usr/lib/$ISA/libpam.so.1\fR\fR 348 .ad 349 .RS 29n 350 File that implements the \fBPAM\fR framework library 351 .RE 352 353 .SH EXAMPLES 354 .LP 355 \fBExample 1 \fRUsing the include control flag 356 .sp 357 .LP 358 The following example collects the common Unix modules into a single file to be 359 included as needed in the example of a \fBpam.conf\fR file. The common Unix 360 module file is named \fBunix_common\fR and consists of: 361 362 .sp 363 .in +2 364 .nf 365 OTHER auth requisite pam_authtok_get.so.1 366 OTHER auth required pam_dhkeys.so.1 367 OTHER auth required pam_unix_auth.so.1 368 OTHER auth required pam_unix_cred.so.1 369 OTHER account requisite pam_roles.so.1 370 OTHER account required pam_unix_account.so.1 371 OTHER session required pam_unix_session.so.1 372 OTHER password required pam_dhkeys.so.1 373 OTHER password requisite pam_authtok_get.so.1 374 OTHER password requisite pam_authtok_check.so.1 375 OTHER password required pam_authtok_store.so.1 376 .fi 377 .in -2 378 .sp 379 380 .sp 381 .LP 382 The \fBpam.conf\fR file and consists of: 383 384 .sp 385 .in +2 386 .nf 387 # Authentication management 388 # 389 # login service (explicit because of pam_dial_auth) 390 # 391 login auth include unix_common 392 login auth required pam_dial_auth.so.1 393 # 394 # rlogin service (explicit because of pam_rhost_auth) 395 # 396 rlogin auth sufficient pam_rhosts_auth.so.1 397 rlogin auth include unix_common 398 # 399 # Default definitions for Authentication management 400 # Used when service name is not explicitly mentioned 401 # 402 OTHER auth include unix_common 403 # 404 # Default definition for Account management 405 # Used when service name is not explicitly mentioned 406 # 407 OTHER account include unix_common 408 # 409 # Default definition for Session management 410 # Used when service name is not explicitly mentioned 411 # 412 OTHER session include unix_common 413 # 414 # Default definition for Password management 415 # Used when service name is not explicitly mentioned 416 # 417 OTHER password include unix_common 418 .fi 419 .in -2 420 .sp 421 422 .SH ATTRIBUTES 423 .LP 424 See \fBattributes\fR(5) for descriptions of the following attributes: 425 .sp 426 427 .sp 428 .TS 429 box; 430 c | c 431 l | l . 432 ATTRIBUTE TYPE ATTRIBUTE VALUE 433 _ 434 Interface Stability See Below. 435 .TE 436 437 .sp 438 .LP 439 The format is Stable. The contents has no stability attributes. 440 .SH SEE ALSO 441 .LP 442 \fBlogin\fR(1), \fBpasswd\fR(1), \fBin.rlogind\fR(1M), 443 \fBin.rshd\fR(1M), \fBin.telnetd\fR(1M), \fBin.uucpd\fR(1M), \fBinit\fR(1M), 444 \fBrpc.rexd\fR(1M), \fBsac\fR(1M), \fBttymon\fR(1M), \fBsu\fR(1M), 445 \fBpam\fR(3PAM), \fBsyslog\fR(3C), \fBlibpam\fR(3LIB), \fBattributes\fR(5), 446 \fBenviron\fR(5), \fBpam_authtok_check\fR(5), \fBpam_authtok_get\fR(5), 447 \fBpam_authtok_store\fR(5), \fBpam_dhkeys\fR(5), \fBpam_krb5\fR(5), 448 \fBpam_passwd_auth\fR(5), \fBpam_unix_account\fR(5), \fBpam_unix_auth\fR(5), 449 \fBpam_unix_session\fR(5) 450 .SH NOTES 451 .LP 452 The \fBpam_unix\fR module is no longer supported. Similar functionality is 453 provided by \fBpam_authtok_check\fR(5), \fBpam_authtok_get\fR(5), 454 \fBpam_authtok_store\fR(5), \fBpam_dhkeys\fR(5), \fBpam_passwd_auth\fR(5), 455 \fBpam_unix_account\fR(5), \fBpam_unix_auth\fR(5), and 456 \fBpam_unix_session\fR(5). 457 .sp 458 .LP 459 With the removal of the \fBpam_unix\fR module, the SunOS delivered PAM service 460 modules no longer need or support the "\fBuse_first_pass\fR" or 461 "\fBtry_first_pass\fR" options. This functionality is provided by stacking 462 \fBpam_authtok_get\fR(5) above a module that requires a password.