[BACK]Return to pam.mdwn CVS log [TXT] [DIR] Up to [NetBSD Developer Wiki] / wikisrc / guide

Diff for /wikisrc/guide/pam.mdwn between versions 1.2 and 1.3

version 1.2, 2013/03/10 02:18:51 version 1.3, 2013/03/10 09:58:15
Line 2 Line 2
   
 ## About  ## About
   
 This article describes the underlying principles and mechanisms of the   This article describes the underlying principles and mechanisms of the
 *Pluggable Authentication Modules (PAM)* library, and explains how to configure   *Pluggable Authentication Modules (PAM)* library, and explains how to configure
 PAM, how to integrate PAM into applications, and how to write PAM modules.  PAM, how to integrate PAM into applications, and how to write PAM modules.
   
 See on the bottom of the page for the license of this text.  See on the bottom of the page for the license of this text.
   
 ## Introduction  ## Introduction
   
 The Pluggable Authentication Modules (PAM) library is a generalized API for   The Pluggable Authentication Modules (PAM) library is a generalized API for
 authentication-related services which allows a system administrator to add new   authentication-related services which allows a system administrator to add new
 authentication methods simply by installing new PAM modules, and to modify   authentication methods simply by installing new PAM modules, and to modify
 authentication policies by editing configuration files.  authentication policies by editing configuration files.
   
 PAM was defined and developed in 1995 by Vipin Samar and Charlie Lai of Sun   PAM was defined and developed in 1995 by Vipin Samar and Charlie Lai of Sun
 Microsystems, and has not changed much since. In 1997, the Open Group published   Microsystems, and has not changed much since. In 1997, the Open Group published
 the X/Open Single Sign-on (XSSO) preliminary specification, which standardized   the X/Open Single Sign-on (XSSO) preliminary specification, which standardized
 the PAM API and added extensions for single (or rather integrated) sign-on. At   the PAM API and added extensions for single (or rather integrated) sign-on. At
 the time of this writing, this specification has not yet been adopted as a   the time of this writing, this specification has not yet been adopted as a
 standard.  standard.
   
 Although this article focuses primarily on FreeBSD 5.x and NetBSD 3.x, which   Although this article focuses primarily on FreeBSD 5.x and NetBSD 3.x, which
 both use OpenPAM, it should be equally applicable to FreeBSD 4.x, which uses   both use OpenPAM, it should be equally applicable to FreeBSD 4.x, which uses
 Linux-PAM, and other operating systems such as Linux and Solaris.  Linux-PAM, and other operating systems such as Linux and Solaris.
   
 ## Terms and conventions  ## Terms and conventions
   
 ### Definitions  ### Definitions
   
 The terminology surrounding PAM is rather confused. Neither Samar and Lai's   The terminology surrounding PAM is rather confused. Neither Samar and Lai's
 original paper nor the XSSO specification made any attempt at formally defining   original paper nor the XSSO specification made any attempt at formally defining
 terms for the various actors and entities involved in PAM, and the terms that   terms for the various actors and entities involved in PAM, and the terms that
 they do use (but do not define) are sometimes misleading and ambiguous. The   they do use (but do not define) are sometimes misleading and ambiguous. The
 first attempt at establishing a consistent and unambiguous terminology was a   first attempt at establishing a consistent and unambiguous terminology was a
 whitepaper written by Andrew G. Morgan (author of Linux-PAM) in 1999. While   whitepaper written by Andrew G. Morgan (author of Linux-PAM) in 1999. While
 Morgan's choice of terminology was a huge leap forward, it is in this author's   Morgan's choice of terminology was a huge leap forward, it is in this author's
 opinion by no means perfect. What follows is an attempt, heavily inspired by   opinion by no means perfect. What follows is an attempt, heavily inspired by
 Morgan, to define precise and unambiguous terms for all actors and entities   Morgan, to define precise and unambiguous terms for all actors and entities
 involved in PAM.  involved in PAM.
   
  * *account* -- The set of credentials the applicant is requesting from the    * *account* -- The set of credentials the applicant is requesting from the
    arbitrator.     arbitrator.
   
  * *applicant* -- The user or entity requesting authentication.   * *applicant* -- The user or entity requesting authentication.
   
  * *arbitrator* -- The user or entity who has the privileges necessary to verify    * *arbitrator* -- The user or entity who has the privileges necessary to verify
    the applicant's credentials and the authority to grant or deny the request.     the applicant's credentials and the authority to grant or deny the request.
   
  * *chain* -- A sequence of modules that will be invoked in response to a PAM    * *chain* -- A sequence of modules that will be invoked in response to a PAM
    request. The chain includes information about the order in which to invoke      request. The chain includes information about the order in which to invoke
    the modules, what arguments to pass to them, and how to interpret the      the modules, what arguments to pass to them, and how to interpret the
    results.     results.
   
  * *client* -- The application responsible for initiating an authentication    * *client* -- The application responsible for initiating an authentication
    request on behalf of the applicant and for obtaining the necessary      request on behalf of the applicant and for obtaining the necessary
    authentication information from him.     authentication information from him.
   
  * *facility* -- One of the four basic groups of functionality provided by PAM:    * *facility* -- One of the four basic groups of functionality provided by PAM:
    authentication, account management, session management and authentication      authentication, account management, session management and authentication
    token update.     token update.
   
  * *module* -- A collection of one or more related functions implementing a    * *module* -- A collection of one or more related functions implementing a
    particular authentication facility, gathered into a single (normally      particular authentication facility, gathered into a single (normally
    dynamically loadable) binary file and identified by a single name.     dynamically loadable) binary file and identified by a single name.
   
  * *policy* -- The complete set of configuration statements describing how to    * *policy* -- The complete set of configuration statements describing how to
    handle PAM requests for a particular service. A policy normally consists of      handle PAM requests for a particular service. A policy normally consists of
    four chains, one for each facility, though some services do not use all four      four chains, one for each facility, though some services do not use all four
    facilities.     facilities.
   
  * *server* -- The application acting on behalf of the arbitrator to converse    * *server* -- The application acting on behalf of the arbitrator to converse
    with the client, retrieve authentication information, verify the applicant's      with the client, retrieve authentication information, verify the applicant's
    credentials and grant or deny requests.     credentials and grant or deny requests.
   
  * *service* -- A class of servers providing similar or related functionality    * *service* -- A class of servers providing similar or related functionality
    and requiring similar authentication. PAM policies are defined on a      and requiring similar authentication. PAM policies are defined on a
    per-service basis, so all servers that claim the same service name will be      per-service basis, so all servers that claim the same service name will be
    subject to the same policy.     subject to the same policy.
   
  * *session* -- The context within which service is rendered to the applicant by    * *session* -- The context within which service is rendered to the applicant by
    the server. One of PAM's four facilities, session management, is concerned      the server. One of PAM's four facilities, session management, is concerned
    exclusively with setting up and tearing down this context.     exclusively with setting up and tearing down this context.
   
  * *token* -- A chunk of information associated with the account, such as a    * *token* -- A chunk of information associated with the account, such as a
    password or passphrase, which the applicant must provide to prove his      password or passphrase, which the applicant must provide to prove his
    identity.     identity.
   
  * *transaction* -- A sequence of requests from the same applicant to the same    * *transaction* -- A sequence of requests from the same applicant to the same
    instance of the same server, beginning with authentication and session set-up      instance of the same server, beginning with authentication and session set-up
    and ending with session tear-down.     and ending with session tear-down.
   
 ### Usage examples  ### Usage examples
   
 This section aims to illustrate the meanings of some of the terms defined above by way of a handful of simple examples.  This section aims to illustrate the meanings of some of the terms defined above
   by way of a handful of simple examples.
   
 #### Client and server are one  #### Client and server are one
   
 This simple example shows `alice` [su(1)](http://netbsd.gw.com/cgi-bin/man-cgi?su+1+NetBSD-5.0.1+i386)'ing to `root`.  This simple example shows `alice`
   [su(1)](http://netbsd.gw.com/cgi-bin/man-cgi?su+1+NetBSD-5.0.1+i386)'ing to
   `root`:
   
     $ whoami      $ whoami
     alice      alice
Line 111  This simple example shows `alice` [su(1) Line 114  This simple example shows `alice` [su(1)
   
  * The applicant is `alice`.   * The applicant is `alice`.
  * The account is `root`.   * The account is `root`.
  * The [su(1)](http://netbsd.gw.com/cgi-bin/man-cgi?su+1+NetBSD-5.0.1+i386) process is both client and server.   * The [su(1)](http://netbsd.gw.com/cgi-bin/man-cgi?su+1+NetBSD-5.0.1+i386)
      process is both client and server.
  * The authentication token is `xi3kiune`.   * The authentication token is `xi3kiune`.
  * The arbitrator is `root`, which is why [su(1)](http://netbsd.gw.com/cgi-bin/man-cgi?su+1+NetBSD-5.0.1+i386) is setuid `root`.   * The arbitrator is `root`, which is why
      [su(1)](http://netbsd.gw.com/cgi-bin/man-cgi?su+1+NetBSD-5.0.1+i386) is
      setuid `root`.
   
 #### Client and server are separate  #### Client and server are separate
   
 The example below shows `eve` try to initiate an   The example below shows `eve` try to initiate an
 [ssh(1)](http://netbsd.gw.com/cgi-bin/man-cgi?ssh+1+NetBSD-5.0.1+i386)   [ssh(1)](http://netbsd.gw.com/cgi-bin/man-cgi?ssh+1+NetBSD-5.0.1+i386)
 connection to `login.example.com`, ask to log in as `bob`, and succeed. Bob   connection to `login.example.com`, ask to log in as `bob`, and succeed. Bob
 should have chosen a better password!  should have chosen a better password!
   
     $ whoami      $ whoami
Line 133  should have chosen a better password! Line 139  should have chosen a better password!
     $      $
   
  * The applicant is `eve`.   * The applicant is `eve`.
  * The client is Eve's [ssh(1)](http://netbsd.gw.com/cgi-bin/man-cgi?ssh+1+NetBSD-5.0.1+i386) process.   * The client is Eve's
  * The server is the [sshd(8)](http://netbsd.gw.com/cgi-bin/man-cgi?sshd+8+NetBSD-5.0.1+i386) process on `login.example.com`     [ssh(1)](http://netbsd.gw.com/cgi-bin/man-cgi?ssh+1+NetBSD-5.0.1+i386)
      process.
    * The server is the
      [sshd(8)](http://netbsd.gw.com/cgi-bin/man-cgi?sshd+8+NetBSD-5.0.1+i386)
      process on `login.example.com`
  * The account is `bob`.   * The account is `bob`.
  * The authentication token is `god`.   * The authentication token is `god`.
  * Although this is not shown in this example, the arbitrator is `root`.   * Although this is not shown in this example, the arbitrator is `root`.
Line 150  The following is FreeBSD's default polic Line 160  The following is FreeBSD's default polic
     sshd    session     required    pam_lastlog.so  no_fail      sshd    session     required    pam_lastlog.so  no_fail
     sshd    password    required    pam_permit.so      sshd    password    required    pam_permit.so
   
  * This policy applies to the `sshd` service (which is not necessarily    * This policy applies to the `sshd` service (which is not necessarily
    restricted to the      restricted to the
    [sshd(8)](http://netbsd.gw.com/cgi-bin/man-cgi?sshd+8+NetBSD-5.0.1+i386)      [sshd(8)](http://netbsd.gw.com/cgi-bin/man-cgi?sshd+8+NetBSD-5.0.1+i386)
    server.)     server.)
   
  * `auth`, `account`, `session` and `password` are facilities.   * `auth`, `account`, `session` and `password` are facilities.
   
  * `pam_nologin.so`, `pam_unix.so`, `pam_login_access.so`, `pam_lastlog.so` and    * `pam_nologin.so`, `pam_unix.so`, `pam_login_access.so`, `pam_lastlog.so` and
    `pam_permit.so` are modules. It is clear from this example that `pam_unix.so`      `pam_permit.so` are modules. It is clear from this example that `pam_unix.so`
    provides at least two facilities (authentication and account management.)     provides at least two facilities (authentication and account management.)
   
 There are some differences between FreeBSD and NetBSD PAM policies:  There are some differences between FreeBSD and NetBSD PAM policies:
   
  * By default, every configuration is done under `/etc/pam.d`.   * By default, every configuration is done under `/etc/pam.d`.
   
  * If configuration is non-existent, you will not have access to the system, in    * If configuration is non-existent, you will not have access to the system, in
    contrast with FreeBSD that has a default policy of allowing authentication.     contrast with FreeBSD that has a default policy of allowing authentication.
   
  * For authentication, NetBSD forces at least one `required`, `requisite` or    * For authentication, NetBSD forces at least one `required`, `requisite` or
    `binding` module to be present.     `binding` module to be present.
   
 ## PAM Essentials  ## PAM Essentials
   
 ### Facilities and primitives  ### Facilities and primitives
   
 The PAM API offers six different authentication primitives grouped in four   The PAM API offers six different authentication primitives grouped in four
 facilities, which are described below.  facilities, which are described below.
   
  * `auth` -- *Authentication.* This facility concerns itself with authenticating    * `auth` -- *Authentication.* This facility concerns itself with authenticating
    the applicant and establishing the account credentials. It provides two      the applicant and establishing the account credentials. It provides two
    primitives:     primitives:
   
         * [pam\_authenticate(3)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_authenticate+3+NetBSD-5.0.1+i386)           * [pam\_authenticate(3)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_authenticate+3+NetBSD-5.0.1+i386)
           authenticates the applicant, usually by requesting an authentication token             authenticates the applicant, usually by requesting an authentication token
           and comparing it with a value stored in a database or obtained from an             and comparing it with a value stored in a database or obtained from an
           authentication server.            authentication server.
   
         * [pam\_setcred(3)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_setcred+3+NetBSD-5.0.1+i386)           * [pam\_setcred(3)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_setcred+3+NetBSD-5.0.1+i386)
           establishes account credentials such as user ID, group membership and             establishes account credentials such as user ID, group membership and
           resource limits.            resource limits.
   
  * `account` -- *Account management.* This facility handles    * `account` -- *Account management.* This facility handles
    non-authentication-related issues of account availability, such as access      non-authentication-related issues of account availability, such as access
    restrictions based on the time of day or the server's work load. It provides      restrictions based on the time of day or the server's work load. It provides
    a single primitive:     a single primitive:
   
         * [pam\_acct\_mgmt(3)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_acct_mgmt+3+NetBSD-5.0.1+i386)           * [pam\_acct\_mgmt(3)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_acct_mgmt+3+NetBSD-5.0.1+i386)
           verifies that the requested account is available.            verifies that the requested account is available.
   
  * `session` -- *Session management.* This facility handles tasks associated    * `session` -- *Session management.* This facility handles tasks associated
    with session set-up and tear-down, such as login accounting. It provides two      with session set-up and tear-down, such as login accounting. It provides two
    primitives:     primitives:
   
         * [pam\_open\_session(3)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_open_session+3+NetBSD-5.0.1+i386)           * [pam\_open\_session(3)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_open_session+3+NetBSD-5.0.1+i386)
           performs tasks associated with session set-up: add an entry in the `utmp`             performs tasks associated with session set-up: add an entry in the `utmp`
           and `wtmp` databases, start an SSH agent, etc.            and `wtmp` databases, start an SSH agent, etc.
   
         * [pam\_close\_session(3)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_close_session+3+NetBSD-5.0.1+i386)           * [pam\_close\_session(3)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_close_session+3+NetBSD-5.0.1+i386)
           performs tasks associated with session tear-down: add an entry in the             performs tasks associated with session tear-down: add an entry in the
           `utmp` and `wtmp` databases, stop the SSH agent, etc.            `utmp` and `wtmp` databases, stop the SSH agent, etc.
   
  * `password` -- *Password management.* This facility is used to change the    * `password` -- *Password management.* This facility is used to change the
    authentication token associated with an account, either because it has      authentication token associated with an account, either because it has
    expired or because the user wishes to change it. It provides a single      expired or because the user wishes to change it. It provides a single
    primitive:     primitive:
   
         * [pam\_chauthtok(3)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_chauthtok+3+NetBSD-5.0.1+i386)           * [pam\_chauthtok(3)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_chauthtok+3+NetBSD-5.0.1+i386)
           changes the authentication token, optionally verifying that it is             changes the authentication token, optionally verifying that it is
           sufficiently hard to guess, has not been used previously, etc.            sufficiently hard to guess, has not been used previously, etc.
   
 ### Modules  ### Modules
   
 Modules are a very central concept in PAM; after all, they are the *M* in *PAM*.   Modules are a very central concept in PAM; after all, they are the *M* in *PAM*.
 A PAM module is a self-contained piece of program code that implements the   A PAM module is a self-contained piece of program code that implements the
 primitives in one or more facilities for one particular mechanism; possible   primitives in one or more facilities for one particular mechanism; possible
 mechanisms for the authentication facility, for instance, include the UNIX®   mechanisms for the authentication facility, for instance, include the UNIX®
 password database, NIS, LDAP and Radius.  password database, NIS, LDAP and Radius.
   
 #### Module Naming  #### Module Naming
   
 FreeBSD and NetBSD implement each mechanism in a single module, named   FreeBSD and NetBSD implement each mechanism in a single module, named
 `pam_mechanism`.so (for instance, `pam_unix.so` for the UNIX mechanism.) Other   `pam_mechanism`.so (for instance, `pam_unix.so` for the UNIX mechanism.) Other
 implementations sometimes have separate modules for separate facilities, and   implementations sometimes have separate modules for separate facilities, and
 include the facility name as well as the mechanism name in the module name. To   include the facility name as well as the mechanism name in the module name. To
 name one example, Solaris has a `pam_dial_auth.so.1` module which is commonly   name one example, Solaris has a `pam_dial_auth.so.1` module which is commonly
 used to authenticate dialup users. Also, almost every module has a man page with   used to authenticate dialup users. Also, almost every module has a man page with
 the same name, i.e.:   the same name, i.e.:
 [pam\_unix(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_unix+8+NetBSD-5.0.1+i386)   [pam\_unix(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_unix+8+NetBSD-5.0.1+i386)
 explains how the `pam_unix.so` module works.  explains how the `pam_unix.so` module works.
   
 #### Module Versioning  #### Module Versioning
   
 FreeBSD's original PAM implementation, based on Linux-PAM, did not use version   FreeBSD's original PAM implementation, based on Linux-PAM, did not use version
 numbers for PAM modules. This would commonly cause problems with legacy   numbers for PAM modules. This would commonly cause problems with legacy
 applications, which might be linked against older versions of the system   applications, which might be linked against older versions of the system
 libraries, as there was no way to load a matching version of the required   libraries, as there was no way to load a matching version of the required
 modules.  modules.
   
 OpenPAM, on the other hand, looks for modules that have the same version number   OpenPAM, on the other hand, looks for modules that have the same version number
 as the PAM library (currently 2 in FreeBSD and 0 in NetBSD), and only falls back   as the PAM library (currently 2 in FreeBSD and 0 in NetBSD), and only falls back
 to an unversioned module if no versioned module could be loaded. Thus legacy   to an unversioned module if no versioned module could be loaded. Thus legacy
 modules can be provided for legacy applications, while allowing new (or newly   modules can be provided for legacy applications, while allowing new (or newly
 built) applications to take advantage of the most recent modules.  built) applications to take advantage of the most recent modules.
   
 Although Solaris PAM modules commonly have a version number, they're not truly   Although Solaris PAM modules commonly have a version number, they're not truly
 versioned, because the number is a part of the module name and must be included   versioned, because the number is a part of the module name and must be included
 in the configuration.  in the configuration.
   
 #### Module Path  #### Module Path
   
 There isn't a common directory for storing PAM modules. Under FreeBSD, they are   There isn't a common directory for storing PAM modules. Under FreeBSD, they are
 located at `/usr/lib` and, under NetBSD, you can find them in   located at `/usr/lib` and, under NetBSD, you can find them in
 `/usr/lib/security`.  `/usr/lib/security`.
   
 ### Chains and policies  ### Chains and policies
   
 When a server initiates a PAM transaction, the PAM library tries to load a   When a server initiates a PAM transaction, the PAM library tries to load a
 policy for the service specified in the   policy for the service specified in the
 [pam\_start(3)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_start+3+NetBSD-5.0.1+i386)   [pam\_start(3)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_start+3+NetBSD-5.0.1+i386)
 call. The policy specifies how authentication requests should be processed, and   call. The policy specifies how authentication requests should be processed, and
 is defined in a configuration file. This is the other central concept in PAM:   is defined in a configuration file. This is the other central concept in PAM:
 the possibility for the admin to tune the system security policy (in the wider   the possibility for the admin to tune the system security policy (in the wider
 sense of the word) simply by editing a text file.  sense of the word) simply by editing a text file.
   
 A policy consists of four chains, one for each of the four PAM facilities. Each   A policy consists of four chains, one for each of the four PAM facilities. Each
 chain is a sequence of configuration statements, each specifying a module to   chain is a sequence of configuration statements, each specifying a module to
 invoke, some (optional) parameters to pass to the module, and a control flag   invoke, some (optional) parameters to pass to the module, and a control flag
 that describes how to interpret the return code from the module.  that describes how to interpret the return code from the module.
   
 Understanding the control flags is essential to understanding PAM configuration   Understanding the control flags is essential to understanding PAM configuration
 files. There are a number of different control flags:  files. There are a number of different control flags:
   
  * `binding` -- If the module succeeds and no earlier module in the chain has    * `binding` -- If the module succeeds and no earlier module in the chain has
    failed, the chain is immediately terminated and the request is granted. If      failed, the chain is immediately terminated and the request is granted. If
    the module fails, the rest of the chain is executed, but the request is      the module fails, the rest of the chain is executed, but the request is
    ultimately denied.     ultimately denied.
   
    This control flag was introduced by Sun in Solaris 9 (SunOS 5.9), and is also supported by OpenPAM.     This control flag was introduced by Sun in Solaris 9 (SunOS 5.9), and is also
      supported by OpenPAM.
   
  * `required` -- If the module succeeds, the rest of the chain is executed, and    * `required` -- If the module succeeds, the rest of the chain is executed, and
    the request is granted unless some other module fails. If the module fails,      the request is granted unless some other module fails. If the module fails,
    the rest of the chain is also executed, but the request is ultimately denied.     the rest of the chain is also executed, but the request is ultimately denied.
   
  * `requisite` -- If the module succeeds, the rest of the chain is executed, and    * `requisite` -- If the module succeeds, the rest of the chain is executed, and
    the request is granted unless some other module fails. If the module fails,      the request is granted unless some other module fails. If the module fails,
    the chain is immediately terminated and the request is denied.     the chain is immediately terminated and the request is denied.
   
  * `sufficient` -- If the module succeeds and no earlier module in the chain has    * `sufficient` -- If the module succeeds and no earlier module in the chain has
    failed, the chain is immediately terminated and the request is granted. If      failed, the chain is immediately terminated and the request is granted. If
    the module fails, the module is ignored and the rest of the chain is      the module fails, the module is ignored and the rest of the chain is
    executed.     executed.
   
    As the semantics of this flag may be somewhat confusing, especially when it is used for the last module in a chain, it is recommended that the `binding` control flag be used instead if the implementation supports it.     As the semantics of this flag may be somewhat confusing, especially when it
      is used for the last module in a chain, it is recommended that the `binding`
      control flag be used instead if the implementation supports it.
   
  * `optional` -- The module is executed, but its result is ignored. If all    * `optional` -- The module is executed, but its result is ignored. If all
    modules in a chain are marked `optional`, all requests will always be      modules in a chain are marked `optional`, all requests will always be
    granted.     granted.
   
 When a server invokes one of the six PAM primitives, PAM retrieves the chain for   When a server invokes one of the six PAM primitives, PAM retrieves the chain for
 the facility the primitive belongs to, and invokes each of the modules listed in   the facility the primitive belongs to, and invokes each of the modules listed in
 the chain, in the order they are listed, until it reaches the end, or determines   the chain, in the order they are listed, until it reaches the end, or determines
 that no further processing is necessary (either because a `binding` or   that no further processing is necessary (either because a `binding` or
 `sufficient` module succeeded, or because a `requisite` module failed.) The   `sufficient` module succeeded, or because a `requisite` module failed.) The
 request is granted if and only if at least one module was invoked, and all   request is granted if and only if at least one module was invoked, and all
 non-optional modules succeeded.  non-optional modules succeeded.
   
 Note that it is possible, though not very common, to have the same module listed   Note that it is possible, though not very common, to have the same module listed
 several times in the same chain. For instance, a module that looks up user names   several times in the same chain. For instance, a module that looks up user names
 and passwords in a directory server could be invoked multiple times with   and passwords in a directory server could be invoked multiple times with
 different parameters specifying different directory servers to contact. PAM   different parameters specifying different directory servers to contact. PAM
 treat different occurrences of the same module in the same chain as different,   treat different occurrences of the same module in the same chain as different,
 unrelated modules.  unrelated modules.
   
 ### Transactions  ### Transactions
   
 The lifecycle of a typical PAM transaction is described below. Note that if any   The lifecycle of a typical PAM transaction is described below. Note that if any
 of these steps fails, the server should report a suitable error message to the   of these steps fails, the server should report a suitable error message to the
 client and abort the transaction.  client and abort the transaction.
   
  1. If necessary, the server obtains arbitrator credentials through a mechanism    1. If necessary, the server obtains arbitrator credentials through a mechanism
     independent of PAM -- most commonly by virtue of having been started by `root`,       independent of PAM -- most commonly by virtue of having been started by `root`,
     or of being setuid `root`.      or of being setuid `root`.
   
  2. The server calls    2. The server calls
     [pam\_start(3)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_start+3+NetBSD-5.0.1+i386)       [pam\_start(3)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_start+3+NetBSD-5.0.1+i386)
     to initialize the PAM library and specify its service name and the target       to initialize the PAM library and specify its service name and the target
     account, and register a suitable conversation function.      account, and register a suitable conversation function.
   
  3. The server obtains various information relating to the transaction (such as    3. The server obtains various information relating to the transaction (such as
     the applicant's user name and the name of the host the client runs on) and       the applicant's user name and the name of the host the client runs on) and
     submits it to PAM using       submits it to PAM using
     [pam\_set\_item(3)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_set_item+3+NetBSD-5.0.1+i386).      [pam\_set\_item(3)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_set_item+3+NetBSD-5.0.1+i386).
   
  4. The server calls    4. The server calls
     [pam\_authenticate(3)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_authenticate+3+NetBSD-5.0.1+i386)       [pam\_authenticate(3)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_authenticate+3+NetBSD-5.0.1+i386)
     to authenticate the applicant.      to authenticate the applicant.
   
  5. The server calls    5. The server calls
     [pam\_acct\_mgmt(3)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_acct_mgmt+3+NetBSD-5.0.1+i386)       [pam\_acct\_mgmt(3)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_acct_mgmt+3+NetBSD-5.0.1+i386)
     to verify that the requested account is available and valid. If the password is       to verify that the requested account is available and valid. If the password is
     correct but has expired,       correct but has expired,
     [pam\_acct\_mgmt(3)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_acct_mgmt+3+NetBSD-5.0.1+i386)       [pam\_acct\_mgmt(3)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_acct_mgmt+3+NetBSD-5.0.1+i386)
     will return `PAM_NEW_AUTHTOK_REQD` instead of `PAM_SUCCESS`.      will return `PAM_NEW_AUTHTOK_REQD` instead of `PAM_SUCCESS`.
   
  6. If the previous step returned `PAM_NEW_AUTHTOK_REQD`, the server now calls    6. If the previous step returned `PAM_NEW_AUTHTOK_REQD`, the server now calls
     [pam\_chauthtok(3)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_chauthtok+3+NetBSD-5.0.1+i386)       [pam\_chauthtok(3)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_chauthtok+3+NetBSD-5.0.1+i386)
     to force the client to change the authentication token for the requested       to force the client to change the authentication token for the requested
     account.      account.
   
  7. Now that the applicant has been properly authenticated, the server calls    7. Now that the applicant has been properly authenticated, the server calls
     [pam\_setcred(3)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_setcred+3+NetBSD-5.0.1+i386)       [pam\_setcred(3)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_setcred+3+NetBSD-5.0.1+i386)
     to establish the credentials of the requested account. It is able to do this       to establish the credentials of the requested account. It is able to do this
     because it acts on behalf of the arbitrator, and holds the arbitrator's       because it acts on behalf of the arbitrator, and holds the arbitrator's
     credentials.      credentials.
   
  8. Once the correct credentials have been established, the server calls    8. Once the correct credentials have been established, the server calls
     [pam\_open\_session(3)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_open_session+3+NetBSD-5.0.1+i386)       [pam\_open\_session(3)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_open_session+3+NetBSD-5.0.1+i386)
     to set up the session.      to set up the session.
   
  9. The server now performs whatever service the client requested -- for    9. The server now performs whatever service the client requested -- for
     instance, provide the applicant with a shell.      instance, provide the applicant with a shell.
   
 10. Once the server is done serving the client, it calls   10. Once the server is done serving the client, it calls
     [pam\_close\_session(3)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_close_session+3+NetBSD-5.0.1+i386)       [pam\_close\_session(3)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_close_session+3+NetBSD-5.0.1+i386)
     to tear down the session.      to tear down the session.
   
 11. Finally, the server calls   11. Finally, the server calls
     [pam\_end(3)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_end+3+NetBSD-5.0.1+i386)       [pam\_end(3)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_end+3+NetBSD-5.0.1+i386)
     to notify the PAM library that it is done and that it can release whatever       to notify the PAM library that it is done and that it can release whatever
     resources it has allocated in the course of the transaction.      resources it has allocated in the course of the transaction.
   
 ## PAM Configuration  ## PAM Configuration
Line 387  client and abort the transaction. Line 400  client and abort the transaction.
   
 #### The `/etc/pam.conf` file  #### The `/etc/pam.conf` file
   
 The traditional PAM policy file is `/etc/pam.conf`. This file contains all the   The traditional PAM policy file is `/etc/pam.conf`. This file contains all the
 PAM policies for your system. Each line of the file describes one step in a   PAM policies for your system. Each line of the file describes one step in a
 chain, as shown below:  chain, as shown below:
   
     login   auth    required        pam_nologin.so  no_warn      login   auth    required        pam_nologin.so  no_warn
   
 The fields are, in order: service name, facility name, control flag, module   The fields are, in order: service name, facility name, control flag, module
 name, and module arguments. Any additional fields are interpreted as additional   name, and module arguments. Any additional fields are interpreted as additional
 module arguments.  module arguments.
   
 A separate chain is constructed for each service / facility pair, so while the   A separate chain is constructed for each service / facility pair, so while the
 order in which lines for the same service and facility appear is significant,   order in which lines for the same service and facility appear is significant,
 the order in which the individual services and facilities are listed is not. The   the order in which the individual services and facilities are listed is not. The
 examples in the original PAM paper grouped configuration lines by facility, and   examples in the original PAM paper grouped configuration lines by facility, and
 the Solaris stock `pam.conf` still does that, but FreeBSD's stock configuration   the Solaris stock `pam.conf` still does that, but FreeBSD's stock configuration
 groups configuration lines by service. Either way is fine; either way makes   groups configuration lines by service. Either way is fine; either way makes
 equal sense.  equal sense.
   
 #### The `/etc/pam.d` directory  #### The `/etc/pam.d` directory
   
 OpenPAM and Linux-PAM support an alternate configuration mechanism, which is the   OpenPAM and Linux-PAM support an alternate configuration mechanism, which is the
 preferred mechanism in FreeBSD and NetBSD. In this scheme, each policy is   preferred mechanism in FreeBSD and NetBSD. In this scheme, each policy is
 contained in a separate file bearing the name of the service it applies to.   contained in a separate file bearing the name of the service it applies to.
 These files are stored in `/etc/pam.d/`.  These files are stored in `/etc/pam.d/`.
   
 These per-service policy files have only four fields instead of `pam.conf`'s   These per-service policy files have only four fields instead of `pam.conf`'s
 five: the service name field is omitted. Thus, instead of the sample `pam.conf`   five: the service name field is omitted. Thus, instead of the sample `pam.conf`
 line from the previous section, one would have the following line in   line from the previous section, one would have the following line in
 `/etc/pam.d/login`:  `/etc/pam.d/login`:
   
     auth    required        pam_nologin.so  no_warn      auth    required        pam_nologin.so  no_warn
   
 As a consequence of this simplified syntax, it is possible to use the same   As a consequence of this simplified syntax, it is possible to use the same
 policy for multiple services by linking each service name to a same policy file.   policy for multiple services by linking each service name to a same policy file.
 For instance, to use the same policy for the `su` and `sudo` services, one could   For instance, to use the same policy for the `su` and `sudo` services, one could
 do as follows:  do as follows:
   
     # cd /etc/pam.d      # cd /etc/pam.d
     # ln -s su sudo      # ln -s su sudo
   
 This works because the service name is determined from the file name rather than   This works because the service name is determined from the file name rather than
 specified in the policy file, so the same file can be used for multiple   specified in the policy file, so the same file can be used for multiple
 differently-named services.  differently-named services.
   
 Since each service's policy is stored in a separate file, the `pam.d` mechanism   Since each service's policy is stored in a separate file, the `pam.d` mechanism
 also makes it very easy to install additional policies for third-party software   also makes it very easy to install additional policies for third-party software
 packages.  packages.
   
 #### The policy search order  #### The policy search order
   
 As we have seen above, PAM policies can be found in a number of places. If no   As we have seen above, PAM policies can be found in a number of places. If no
 configuration file is found for a particular service, the `/etc/pam.d/other` is   configuration file is found for a particular service, the `/etc/pam.d/other` is
 used instead. If that file does not exist, `/etc/pam.conf` is searched for   used instead. If that file does not exist, `/etc/pam.conf` is searched for
 entries matching he specified service or, failing that, the "other" service.  entries matching he specified service or, failing that, the "other" service.
   
 It is essential to understand that PAM's configuration system is centered on   It is essential to understand that PAM's configuration system is centered on
 chains.  chains.
   
 ### Breakdown of a configuration line  ### Breakdown of a configuration line
   
 As explained in the [PAM policy files](chap-pam.html#pam-config-file "18.5.1.   As explained in the [PAM policy files](chap-pam.html#pam-config-file "18.5.1.
 PAM policy files") section, each line in `/etc/pam.conf` consists of four or   PAM policy files") section, each line in `/etc/pam.conf` consists of four or
 more fields: the service name, the facility name, the control flag, the module   more fields: the service name, the facility name, the control flag, the module
 name, and zero or more module arguments.  name, and zero or more module arguments.
   
 The service name is generally (though not always) the name of the application   The service name is generally (though not always) the name of the application
 the statement applies to. If you are unsure, refer to the individual   the statement applies to. If you are unsure, refer to the individual
 application's documentation to determine what service name it uses.  application's documentation to determine what service name it uses.
   
 Note that if you use `/etc/pam.d/` instead of `/etc/pam.conf`, the service name   Note that if you use `/etc/pam.d/` instead of `/etc/pam.conf`, the service name
 is specified by the name of the policy file, and omitted from the actual   is specified by the name of the policy file, and omitted from the actual
 configuration lines, which then start with the facility name.  configuration lines, which then start with the facility name.
   
 The facility is one of the four facility keywords described in the  The facility is one of the four facility keywords described in the
 [[Facilities and primitives|guide/pam#facilities-primitives]]] section.  [[Facilities and primitives|guide/pam#facilities-primitives]]] section.
   
 Likewise, the control flag is one of the four keywords described in the [[Chains   Likewise, the control flag is one of the four keywords described in the [[Chains
 and policies|guide/pam#chains-policies]] section, describing how to interpret   and policies|guide/pam#chains-policies]] section, describing how to interpret
 the return code from the module. Linux-PAM supports an alternate syntax that   the return code from the module. Linux-PAM supports an alternate syntax that
 lets you specify the action to associate with each possible return code, but   lets you specify the action to associate with each possible return code, but
 this should be avoided as it is non-standard and closely tied in with the way   this should be avoided as it is non-standard and closely tied in with the way
 Linux-PAM dispatches service calls (which differs greatly from the way Solaris   Linux-PAM dispatches service calls (which differs greatly from the way Solaris
 and OpenPAM do it.) Unsurprisingly, OpenPAM does not support this syntax.  and OpenPAM do it.) Unsurprisingly, OpenPAM does not support this syntax.
   
 ### Policies  ### Policies
   
 To configure PAM correctly, it is essential to understand how policies are   To configure PAM correctly, it is essential to understand how policies are
 interpreted.  interpreted.
   
 When an application calls   When an application calls
 [pam\_start(3)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_start+3+NetBSD-5.0.1+i386),   [pam\_start(3)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_start+3+NetBSD-5.0.1+i386),
 the PAM library loads the policy for the specified service and constructs four   the PAM library loads the policy for the specified service and constructs four
 module chains (one for each facility.) If one or more of these chains are empty,   module chains (one for each facility.) If one or more of these chains are empty,
 the corresponding chains from the policy for the `other` service are   the corresponding chains from the policy for the `other` service are
 substituted.  substituted.
   
 When the application later calls one of the six PAM primitives, the PAM library   When the application later calls one of the six PAM primitives, the PAM library
 retrieves the chain for the corresponding facility and calls the appropriate   retrieves the chain for the corresponding facility and calls the appropriate
 service function in each module listed in the chain, in the order in which they   service function in each module listed in the chain, in the order in which they
 were listed in the configuration. After each call to a service function, the   were listed in the configuration. After each call to a service function, the
 module type and the error code returned by the service function are used to   module type and the error code returned by the service function are used to
 determine what happens next. With a few exceptions, which we discuss below, the   determine what happens next. With a few exceptions, which we discuss below, the
 following table applies:  following table applies:
   
 [[!table data="""  [[!table data="""
Line 500  sufficient | if (!fail) break; |      -  Line 513  sufficient | if (!fail) break; |      - 
 optional   |         -         |      -       |          -  optional   |         -         |      -       |          -
 """]]  """]]
   
 If `fail` is true at the end of a chain, or when a `break` is reached, the   If `fail` is true at the end of a chain, or when a `break` is reached, the
 dispatcher returns the error code returned by the first module that failed.   dispatcher returns the error code returned by the first module that failed.
 Otherwise, it returns `PAM_SUCCESS`.  Otherwise, it returns `PAM_SUCCESS`.
   
 The first exception of note is that the error code `PAM_NEW_AUTHTOK_REQD` is   The first exception of note is that the error code `PAM_NEW_AUTHTOK_REQD` is
 treated like a success, except that if no module failed, and at least one module   treated like a success, except that if no module failed, and at least one module
 returned `PAM_NEW_AUTHTOK_REQD`, the dispatcher will return   returned `PAM_NEW_AUTHTOK_REQD`, the dispatcher will return
 `PAM_NEW_AUTHTOK_REQD`.  `PAM_NEW_AUTHTOK_REQD`.
   
 The second exception is that   The second exception is that
 [pam\_setcred(3)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_setcred+3+NetBSD-5.0.1+i386)   [pam\_setcred(3)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_setcred+3+NetBSD-5.0.1+i386)
 treats `binding` and `sufficient` modules as if they were `required`.  treats `binding` and `sufficient` modules as if they were `required`.
   
 The third and final exception is that   The third and final exception is that
 [pam\_chauthtok(3)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_chauthtok+3+NetBSD-5.0.1+i386)   [pam\_chauthtok(3)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_chauthtok+3+NetBSD-5.0.1+i386)
 runs the entire chain twice (once for preliminary checks and once to actually   runs the entire chain twice (once for preliminary checks and once to actually
 set the password), and in the preliminary phase it treats `binding` and   set the password), and in the preliminary phase it treats `binding` and
 `sufficient` modules as if they were `required`.  `sufficient` modules as if they were `required`.
   
 ## PAM modules  ## PAM modules
Line 525  set the password), and in the preliminar Line 538  set the password), and in the preliminar
   
 #### pam\_deny(8)  #### pam\_deny(8)
   
 The   The
 [pam\_deny(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_deny+8+NetBSD-5.0.1+i386)   [pam\_deny(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_deny+8+NetBSD-5.0.1+i386)
 module is one of the simplest modules available; it responds to any request with   module is one of the simplest modules available; it responds to any request with
 `PAM_AUTH_ERR`. It is useful for quickly disabling a service (add it to the top   `PAM_AUTH_ERR`. It is useful for quickly disabling a service (add it to the top
 of every chain), or for terminating chains of `sufficient` modules.  of every chain), or for terminating chains of `sufficient` modules.
   
 #### pam\_echo(8)  #### pam\_echo(8)
   
 The   The
 [pam\_echo(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_echo+8+NetBSD-5.0.1+i386)   [pam\_echo(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_echo+8+NetBSD-5.0.1+i386)
 module simply passes its arguments to the conversation function as a   module simply passes its arguments to the conversation function as a
 `PAM_TEXT_INFO` message. It is mostly useful for debugging, but can also serve   `PAM_TEXT_INFO` message. It is mostly useful for debugging, but can also serve
 to display messages such as `Unauthorized access will be prosecuted` before   to display messages such as `Unauthorized access will be prosecuted` before
 starting the authentication procedure.  starting the authentication procedure.
   
 #### pam\_exec(8)  #### pam\_exec(8)
   
 The   The
 [pam\_exec(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_exec+8+NetBSD-5.0.1+i386)   [pam\_exec(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_exec+8+NetBSD-5.0.1+i386)
 module takes its first argument to be the name of a program to execute, and the   module takes its first argument to be the name of a program to execute, and the
 remaining arguments are passed to that program as command-line arguments. One   remaining arguments are passed to that program as command-line arguments. One
 possible application is to use it to run a program at login time which mounts   possible application is to use it to run a program at login time which mounts
 the user's home directory.  the user's home directory.
   
 #### pam\_ftpusers(8)  #### pam\_ftpusers(8)
   
 The   The
 [pam\_ftpusers(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_ftpusers+8+NetBSD-5.0.1+i386)   [pam\_ftpusers(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_ftpusers+8+NetBSD-5.0.1+i386)
 module successes if and only if the user is listed in `/etc/ftpusers`.   module successes if and only if the user is listed in `/etc/ftpusers`.
 Currently, in NetBSD, this module doesn't understand the extended syntax of   Currently, in NetBSD, this module doesn't understand the extended syntax of
 [ftpd(8)](http://netbsd.gw.com/cgi-bin/man-cgi?ftpd+8+NetBSD-5.0.1+i386), but   [ftpd(8)](http://netbsd.gw.com/cgi-bin/man-cgi?ftpd+8+NetBSD-5.0.1+i386), but
 this will be fixed in the future.  this will be fixed in the future.
   
 #### pam\_group(8)  #### pam\_group(8)
   
 The   The
 [pam\_group(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_group+8+NetBSD-5.0.1+i386)   [pam\_group(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_group+8+NetBSD-5.0.1+i386)
 module accepts or rejects applicants on the basis of their membership in a   module accepts or rejects applicants on the basis of their membership in a
 particular file group (normally `wheel` for   particular file group (normally `wheel` for
 [su(1)](http://netbsd.gw.com/cgi-bin/man-cgi?su+1+NetBSD-5.0.1+i386)). It is   [su(1)](http://netbsd.gw.com/cgi-bin/man-cgi?su+1+NetBSD-5.0.1+i386)). It is
 primarily intended for maintaining the traditional behaviour of BSD   primarily intended for maintaining the traditional behaviour of BSD
 [su(1)](http://netbsd.gw.com/cgi-bin/man-cgi?su+1+NetBSD-5.0.1+i386), but has   [su(1)](http://netbsd.gw.com/cgi-bin/man-cgi?su+1+NetBSD-5.0.1+i386), but has
 many other uses, such as excluding certain groups of users from a particular   many other uses, such as excluding certain groups of users from a particular
 service.  service.
   
 In NetBSD, there is an argument called `authenticate` in which the user is asked   In NetBSD, there is an argument called `authenticate` in which the user is asked
 to authenticate using his own password.  to authenticate using his own password.
   
 #### pam\_guest(8)  #### pam\_guest(8)
   
 The   The
 [pam\_guest(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_guest+8+NetBSD-5.0.1+i386)   [pam\_guest(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_guest+8+NetBSD-5.0.1+i386)
 module allows guest logins using fixed login names. Various requirements can be   module allows guest logins using fixed login names. Various requirements can be
 placed on the password, but the default behaviour is to allow any password as   placed on the password, but the default behaviour is to allow any password as
 long as the login name is that of a guest account. The   long as the login name is that of a guest account. The
 [pam\_guest(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_guest+8+NetBSD-5.0.1+i386)   [pam\_guest(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_guest+8+NetBSD-5.0.1+i386)
 module can easily be used to implement anonymous FTP logins.  module can easily be used to implement anonymous FTP logins.
   
 #### pam\_krb5(8)  #### pam\_krb5(8)
   
 The   The
 [pam\_krb5(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_krb5+8+NetBSD-5.0.1+i386)   [pam\_krb5(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_krb5+8+NetBSD-5.0.1+i386)
 module provides functions to verify the identity of a user and to set user   module provides functions to verify the identity of a user and to set user
 specific credentials using Kerberos 5. It prompts the user for a password and   specific credentials using Kerberos 5. It prompts the user for a password and
 obtains a new Kerberos TGT for the principal. The TGT is verified by obtaining a   obtains a new Kerberos TGT for the principal. The TGT is verified by obtaining a
 service ticket for the local host. The newly acquired credentials are stored in   service ticket for the local host. The newly acquired credentials are stored in
 a credential cache and the environment variable KRB5CCNAME is set appropriately.   a credential cache and the environment variable KRB5CCNAME is set appropriately.
 The credentials cache should be destroyed by the user at logout with   The credentials cache should be destroyed by the user at logout with
 [kdestroy(1)](http://netbsd.gw.com/cgi-bin/man-cgi?kdestroy+1+NetBSD-5.0.1+i386).  [kdestroy(1)](http://netbsd.gw.com/cgi-bin/man-cgi?kdestroy+1+NetBSD-5.0.1+i386).
   
 #### pam\_ksu(8)  #### pam\_ksu(8)
   
 The   The
 [pam\_ksu(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_ksu+8+NetBSD-5.0.1+i386)   [pam\_ksu(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_ksu+8+NetBSD-5.0.1+i386)
 module provides only authentication services for Kerberos 5 to determine whether   module provides only authentication services for Kerberos 5 to determine whether
 or not the applicant is authorized to obtain the privileges of the target   or not the applicant is authorized to obtain the privileges of the target
 account.  account.
   
 #### pam\_lastlog(8)  #### pam\_lastlog(8)
   
 The   The
 [pam\_lastlog(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_lastlog+8+NetBSD-5.0.1+i386)   [pam\_lastlog(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_lastlog+8+NetBSD-5.0.1+i386)
 module provides only session management services. It records the session in   module provides only session management services. It records the session in
 [utmp(5)](http://netbsd.gw.com/cgi-bin/man-cgi?utmp+5+NetBSD-5.0.1+i386),   [utmp(5)](http://netbsd.gw.com/cgi-bin/man-cgi?utmp+5+NetBSD-5.0.1+i386),
 [utmpx(5)](http://netbsd.gw.com/cgi-bin/man-cgi?utmpx+5+NetBSD-5.0.1+i386),   [utmpx(5)](http://netbsd.gw.com/cgi-bin/man-cgi?utmpx+5+NetBSD-5.0.1+i386),
 [wtmp(5)](http://netbsd.gw.com/cgi-bin/man-cgi?wtmp+5+NetBSD-5.0.1+i386),   [wtmp(5)](http://netbsd.gw.com/cgi-bin/man-cgi?wtmp+5+NetBSD-5.0.1+i386),
 [wtmpx(5)](http://netbsd.gw.com/cgi-bin/man-cgi?wtmpx+5+NetBSD-5.0.1+i386),   [wtmpx(5)](http://netbsd.gw.com/cgi-bin/man-cgi?wtmpx+5+NetBSD-5.0.1+i386),
 [lastlog(5)](http://netbsd.gw.com/cgi-bin/man-cgi?lastlog+5+NetBSD-5.0.1+i386)   [lastlog(5)](http://netbsd.gw.com/cgi-bin/man-cgi?lastlog+5+NetBSD-5.0.1+i386)
 and   and
 [lastlogx(5)](http://netbsd.gw.com/cgi-bin/man-cgi?lastlogx+5+NetBSD-5.0.1+i386)   [lastlogx(5)](http://netbsd.gw.com/cgi-bin/man-cgi?lastlogx+5+NetBSD-5.0.1+i386)
 databases.  databases.
   
 #### pam\_login\_access(8)  #### pam\_login\_access(8)
   
 The   The
 [pam\_login\_access(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_login_access+8+NetBSD-5.0.1+i386)   [pam\_login\_access(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_login_access+8+NetBSD-5.0.1+i386)
 module provides an implementation of the account management primitive which   module provides an implementation of the account management primitive which
 enforces the login restrictions specified in the   enforces the login restrictions specified in the
 [login.access(5)](http://netbsd.gw.com/cgi-bin/man-cgi?login.access+5+NetBSD-5.0.1+i386)   [login.access(5)](http://netbsd.gw.com/cgi-bin/man-cgi?login.access+5+NetBSD-5.0.1+i386)
 table.  table.
   
 #### pam\_nologin(8)  #### pam\_nologin(8)
   
 The   The
 [pam\_nologin(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_nologin+8+NetBSD-5.0.1+i386)   [pam\_nologin(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_nologin+8+NetBSD-5.0.1+i386)
 module refuses non-root logins when `/var/run/nologin` exists. This file is   module refuses non-root logins when `/var/run/nologin` exists. This file is
 normally created by   normally created by
 [shutdown(8)](http://netbsd.gw.com/cgi-bin/man-cgi?shutdown+8+NetBSD-5.0.1+i386)   [shutdown(8)](http://netbsd.gw.com/cgi-bin/man-cgi?shutdown+8+NetBSD-5.0.1+i386)
 when less than five minutes remain until the scheduled shutdown time.  when less than five minutes remain until the scheduled shutdown time.
   
 #### pam\_permit(8)  #### pam\_permit(8)
   
 The   The
 [pam\_permit(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_permit+8+NetBSD-5.0.1+i386)   [pam\_permit(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_permit+8+NetBSD-5.0.1+i386)
 module is one of the simplest modules available; it responds to any request with   module is one of the simplest modules available; it responds to any request with
 `PAM_SUCCESS`. It is useful as a placeholder for services where one or more   `PAM_SUCCESS`. It is useful as a placeholder for services where one or more
 chains would otherwise be empty.  chains would otherwise be empty.
   
 #### pam\_radius(8)  #### pam\_radius(8)
   
 The   The
 [pam\_radius(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_radius+8+NetBSD-5.0.1+i386)   [pam\_radius(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_radius+8+NetBSD-5.0.1+i386)
 module provides authentication services based upon the RADIUS (Remote   module provides authentication services based upon the RADIUS (Remote
 Authentication Dial In User Service) protocol.  Authentication Dial In User Service) protocol.
   
 #### pam\_rhosts(8)  #### pam\_rhosts(8)
   
 The   The
 [pam\_rhosts(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_rhosts+8+NetBSD-5.0.1+i386)   [pam\_rhosts(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_rhosts+8+NetBSD-5.0.1+i386)
 module provides only authentication services. It reports success if and only if   module provides only authentication services. It reports success if and only if
 the target user's ID is not 0 and the remote host and user are listed in   the target user's ID is not 0 and the remote host and user are listed in
 `/etc/hosts.equiv` or in the target user's `~/.rhosts`.  `/etc/hosts.equiv` or in the target user's `~/.rhosts`.
   
 #### pam\_rootok(8)  #### pam\_rootok(8)
   
 The   The
 [pam\_rootok(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_rootok+8+NetBSD-5.0.1+i386)   [pam\_rootok(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_rootok+8+NetBSD-5.0.1+i386)
 module reports success if and only if the real user id of the process calling it   module reports success if and only if the real user id of the process calling it
 (which is assumed to be run by the applicant) is 0. This is useful for   (which is assumed to be run by the applicant) is 0. This is useful for
 non-networked services such as   non-networked services such as
 [su(1)](http://netbsd.gw.com/cgi-bin/man-cgi?su+1+NetBSD-5.0.1+i386) or   [su(1)](http://netbsd.gw.com/cgi-bin/man-cgi?su+1+NetBSD-5.0.1+i386) or
 [passwd(1)](http://netbsd.gw.com/cgi-bin/man-cgi?passwd+1+NetBSD-5.0.1+i386), to   [passwd(1)](http://netbsd.gw.com/cgi-bin/man-cgi?passwd+1+NetBSD-5.0.1+i386), to
 which the `root` should have automatic access.  which the `root` should have automatic access.
   
 #### pam\_securetty(8)  #### pam\_securetty(8)
   
 The   The
 [pam\_securetty(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_securetty+8+NetBSD-5.0.1+i386)   [pam\_securetty(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_securetty+8+NetBSD-5.0.1+i386)
 module provides only account services. It is used when the applicant is   module provides only account services. It is used when the applicant is
 attempting to authenticate as superuser, and the process is attached to an   attempting to authenticate as superuser, and the process is attached to an
 insecure TTY.  insecure TTY.
   
 #### pam\_self(8)  #### pam\_self(8)
   
 The   The
 [pam\_self(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_self+8+NetBSD-5.0.1+i386)   [pam\_self(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_self+8+NetBSD-5.0.1+i386)
 module reports success if and only if the names of the applicant matches that of   module reports success if and only if the names of the applicant matches that of
 the target account. It is most useful for non-networked services such as   the target account. It is most useful for non-networked services such as
 [su(1)](http://netbsd.gw.com/cgi-bin/man-cgi?su+1+NetBSD-5.0.1+i386), where the   [su(1)](http://netbsd.gw.com/cgi-bin/man-cgi?su+1+NetBSD-5.0.1+i386), where the
 identity of the applicant can be easily verified.  identity of the applicant can be easily verified.
   
 #### pam\_ssh(8)  #### pam\_ssh(8)
   
 The   The
 [pam\_ssh(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_ssh+8+NetBSD-5.0.1+i386)   [pam\_ssh(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_ssh+8+NetBSD-5.0.1+i386)
 module provides both authentication and session services. The authentication   module provides both authentication and session services. The authentication
 service allows users who have passphrase-protected SSH secret keys in their   service allows users who have passphrase-protected SSH secret keys in their
 `~/.ssh` directory to authenticate themselves by typing their passphrase. The   `~/.ssh` directory to authenticate themselves by typing their passphrase. The
 session service starts   session service starts
 [ssh-agent(1)](http://netbsd.gw.com/cgi-bin/man-cgi?ssh-agent+1+NetBSD-5.0.1+i386)   [ssh-agent(1)](http://netbsd.gw.com/cgi-bin/man-cgi?ssh-agent+1+NetBSD-5.0.1+i386)
 and preloads it with the keys that were decrypted in the authentication phase.   and preloads it with the keys that were decrypted in the authentication phase.
 This feature is particularly useful for local logins, whether in X (using   This feature is particularly useful for local logins, whether in X (using
 [xdm(1)](http://netbsd.gw.com/cgi-bin/man-cgi?xdm+1+NetBSD-5.0.1+i386) or   [xdm(1)](http://netbsd.gw.com/cgi-bin/man-cgi?xdm+1+NetBSD-5.0.1+i386) or
 another PAM-aware X login manager) or at the console.  another PAM-aware X login manager) or at the console.
   
 This module implements what is fundamentally a password authentication scheme.   This module implements what is fundamentally a password authentication scheme.
 Care should be taken to only use this module over a secure session (secure TTY,   Care should be taken to only use this module over a secure session (secure TTY,
 encrypted session, etc.), otherwise the user's SSH passphrase could be   encrypted session, etc.), otherwise the user's SSH passphrase could be
 compromised.  compromised.
   
 Additional consideration should be given to the use of   Additional consideration should be given to the use of
 [pam\_ssh(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_ssh+8+NetBSD-5.0.1+i386).   [pam\_ssh(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_ssh+8+NetBSD-5.0.1+i386).
 Users often assume that file permissions are sufficient to protect their SSH   Users often assume that file permissions are sufficient to protect their SSH
 keys, and thus use weak or no passphrases. Since the system administrator has no   keys, and thus use weak or no passphrases. Since the system administrator has no
 effective means of enforcing SSH passphrase quality, this has the potential to   effective means of enforcing SSH passphrase quality, this has the potential to
 expose the system to security risks.  expose the system to security risks.
   
 #### pam\_unix(8)  #### pam\_unix(8)
   
 The   The
 [pam\_unix(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_unix+8+NetBSD-5.0.1+i386)   [pam\_unix(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_unix+8+NetBSD-5.0.1+i386)
 module implements traditional UNIX® password authentication, using   module implements traditional UNIX® password authentication, using
 [getpwnam(3)](http://netbsd.gw.com/cgi-bin/man-cgi?getpwnam+3+NetBSD-5.0.1+i386)   [getpwnam(3)](http://netbsd.gw.com/cgi-bin/man-cgi?getpwnam+3+NetBSD-5.0.1+i386)
 under FreeBSD or   under FreeBSD or
 [getpwnam\_r(3)](http://netbsd.gw.com/cgi-bin/man-cgi?getpwnam_r+3+NetBSD-5.0.1+i386)   [getpwnam\_r(3)](http://netbsd.gw.com/cgi-bin/man-cgi?getpwnam_r+3+NetBSD-5.0.1+i386)
 under NetBSD to obtain the target account's password and compare it with the one   under NetBSD to obtain the target account's password and compare it with the one
 provided by the applicant. It also provides account management services   provided by the applicant. It also provides account management services
 (enforcing account and password expiration times) and password-changing   (enforcing account and password expiration times) and password-changing
 services. This is probably the single most useful module, as the great majority   services. This is probably the single most useful module, as the great majority
 of admins will want to maintain historical behaviour for at least some services.  of admins will want to maintain historical behaviour for at least some services.
   
 ### NetBSD-specific PAM Modules  ### NetBSD-specific PAM Modules
   
 #### pam\_skey(8)  #### pam\_skey(8)
   
 The   The
 [pam\_skey(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_skey+8+NetBSD-5.0.1+i386)   [pam\_skey(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_skey+8+NetBSD-5.0.1+i386)
 module implements S/Key One Time Password (OTP) authentication methods, using   module implements S/Key One Time Password (OTP) authentication methods, using
 the `/etc/skeykeys` database.  the `/etc/skeykeys` database.
   
 ## PAM Application Programming  ## PAM Application Programming
Line 745  This section has not yet been written. Line 758  This section has not yet been written.
   
 ## Sample PAM Application  ## Sample PAM Application
   
 The following is a minimal implementation of   The following is a minimal implementation of
 [su(1)](http://netbsd.gw.com/cgi-bin/man-cgi?su+1+NetBSD-5.0.1+i386) using PAM.   [su(1)](http://netbsd.gw.com/cgi-bin/man-cgi?su+1+NetBSD-5.0.1+i386) using PAM.
 Note that it uses the OpenPAM-specific   Note that it uses the OpenPAM-specific
 [openpam\_ttyconv(3)](http://netbsd.gw.com/cgi-bin/man-cgi?openpam_ttyconv+3+NetBSD-5.0.1+i386)   [openpam\_ttyconv(3)](http://netbsd.gw.com/cgi-bin/man-cgi?openpam_ttyconv+3+NetBSD-5.0.1+i386)
 conversation function, which is prototyped in `security/openpam.h`. If you wish   conversation function, which is prototyped in `security/openpam.h`. If you wish
 build this application on a system with a different PAM library, you will have   build this application on a system with a different PAM library, you will have
 to provide your own conversation function. A robust conversation function is   to provide your own conversation function. A robust conversation function is
 surprisingly difficult to implement; the one presented in the [Sample PAM   surprisingly difficult to implement; the one presented in the [Sample PAM
 Conversation Function](chap-pam.html#pam-sample-conv "18.11. Sample PAM   Conversation Function](chap-pam.html#pam-sample-conv "18.11. Sample PAM
 Conversation Function") sub-chapter is a good starting point, but should not be   Conversation Function") sub-chapter is a good starting point, but should not be
 used in real-world applications.  used in real-world applications.
   
     #include <sys/param.h>      #include <sys/param.h>
Line 909  used in real-world applications. Line 922  used in real-world applications.
   
 ## Sample PAM Module  ## Sample PAM Module
   
 The following is a minimal implementation of   The following is a minimal implementation of
 [pam\_unix(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_unix+8+NetBSD-5.0.1+i386),   [pam\_unix(8)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_unix+8+NetBSD-5.0.1+i386),
 offering only authentication services. It should build and run with most PAM   offering only authentication services. It should build and run with most PAM
 implementations, but takes advantage of OpenPAM extensions if available: note   implementations, but takes advantage of OpenPAM extensions if available: note
 the use of   the use of
 [pam\_get\_authtok(3)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_get_authtok+3+NetBSD-5.0.1+i386),   [pam\_get\_authtok(3)](http://netbsd.gw.com/cgi-bin/man-cgi?pam_get_authtok+3+NetBSD-5.0.1+i386),
 which enormously simplifies prompting the user for a password.  which enormously simplifies prompting the user for a password.
   
     #include <sys/param.h>      #include <sys/param.h>
Line 1051  which enormously simplifies prompting th Line 1064  which enormously simplifies prompting th
   
 ## Sample PAM Conversation Function  ## Sample PAM Conversation Function
   
 The conversation function presented below is a greatly simplified version of   The conversation function presented below is a greatly simplified version of
 OpenPAM's   OpenPAM's
 [openpam\_ttyconv(3)](http://netbsd.gw.com/cgi-bin/man-cgi?openpam_ttyconv+3+NetBSD-5.0.1+i386).   [openpam\_ttyconv(3)](http://netbsd.gw.com/cgi-bin/man-cgi?openpam_ttyconv+3+NetBSD-5.0.1+i386).
 It is fully functional, and should give the reader a good idea of how a   It is fully functional, and should give the reader a good idea of how a
 conversation function should behave, but it is far too simple for real-world   conversation function should behave, but it is far too simple for real-world
 use. Even if you're not using OpenPAM, feel free to download the source code and   use. Even if you're not using OpenPAM, feel free to download the source code and
 adapt   adapt
 [openpam\_ttyconv(3)](http://netbsd.gw.com/cgi-bin/man-cgi?openpam_ttyconv+3+NetBSD-5.0.1+i386)   [openpam\_ttyconv(3)](http://netbsd.gw.com/cgi-bin/man-cgi?openpam_ttyconv+3+NetBSD-5.0.1+i386)
 to your uses; we believe it to be as robust as a tty-oriented conversation   to your uses; we believe it to be as robust as a tty-oriented conversation
 function can reasonably get.  function can reasonably get.
   
     #include <stdio.h>      #include <stdio.h>
Removed from v.1.2  
changed lines
  Added in v.1.3

CVSweb for NetBSD wikisrc <wikimaster@NetBSD.org> software: FreeBSD-CVSweb