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