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