$FreeBSD: doc/en_US.ISO8859-1/articles/pam/article.sgml,v 1.11 2002/02/28 15:03:07 chris Exp $ This article describes the underlying principles and mechanisms of the Pluggable Authentication Modules (PAM) library, and explains how to configure PAM, how to integrate PAM into applications, and how to write PAM modules. Dag-Erling Smørgrav Contributed by

The Pluggable Authentication Modules (PAM) library is a generalized API for authentication-related services which allows a system administrator to add new authentication methods simply by installing new PAM modules, and to modify authentication policies by editing configuration files. 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 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 time of this writing, this specification has not yet been adopted as a standard. Although this article focuses on FreeBSD's implementation of PAM, which is based on Linux-PAM, most of it should be applicable to most other operating systems which implement PAM, including Solaris.

Sun, Sun Microsystems and Solaris are trademarks or registered trademarks of Sun Microsystems, Inc. UNIX and The Open Group are trademarks or registered trademarks of The Open Group. All other brand or product names mentioned in this document may be trademarks or registered trademarks of their respective owners.

The terminology surrounding PAM is rather confused. Neither Samar and Lai's 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 they do use (but do not define) are sometimes misleading and ambiguous. The first attempt at establishing a consistent and unambiguous terminology was a 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 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 involved in PAM. account The set of credentials the applicant is requesting from the arbitrator. applicant The user or entity requesting authentication. 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. 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 the modules, what arguments to pass to them, and how to interpret the results. client The application responsible for initiating an authentication request on behalf of the applicant and for obtaining the necessary authentication information from him. facility One of the four basic groups of functionality provided by PAM: authentication, account management, session management and authentication token update. module A collection of one or more related functions implementing a particular authentication facility, gathered into a single (normally dynamically loadable) binary file and identified by a single name. policy The complete set of configuration statements describing how to 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 facilities. server The application acting on behalf of the arbitrator to converse with the client, retrieve authentication information, verify the applicant's credentials and grant or deny requests. service A class of servers providing similar or related functionality and requiring similar authentication. PAM policies are defined on a per-service basis, so all servers that claim the same service name will be subject to the same policy. session The context within which service is rendered to the applicant by the server. One of PAM's four facilities, session management, is concerned exclusively with setting up and tearing down this context. token A chunk of information associated with the account, such as a password or passphrase, which the applicant must provide to prove his identity. transaction A sequence of requests from the same applicant to the same instance of the same server, beginning with authentication and session set-up and ending with session tear-down.

This section aims to illustrate the meanings of some of the terms defined above by way of a handful of simple examples.

This simple example shows alice &man.su.1;'ing to root. &prompt.user; whoami alice &prompt.user; ls -l `which su` -r-sr-xr-x 1 root wheel 10744 Dec 6 19:06 /usr/bin/su &prompt.user; su - Password: xi3kiune &prompt.root; whoami root The applicant is alice. The account is root. The &man.su.1; process is both client and server. The authentication token is xi3kiune. The arbitrator is root, which is why &man.su.1; is setuid root.

The example below shows eve try to initiate an &man.ssh.1; connection to login.example.com, ask to log in as bob, and succeed. Bob should have chosen a better password! &prompt.user; whoami eve &prompt.user; ssh bob@login.example.com bob@login.example.com's password: god Last login: Thu Oct 11 09:52:57 2001 from 192.168.0.1 Copyright (c) 1980, 1983, 1986, 1988, 1990, 1991, 1993, 1994 The Regents of the University of California. All rights reserved. FreeBSD 4.4-STABLE (LOGIN) #4: Tue Nov 27 18:10:34 PST 2001 Welcome to FreeBSD! &prompt.user; The applicant is eve. The client is Eve's &man.ssh.1; process. The server is the &man.sshd.8; process on login.example.com The account is bob. The authentication token is god. Although this is not shown in this example, the arbitrator is root.

The following is FreeBSD's default policy for sshd: sshd auth required pam_nologin.so no_warn sshd auth required pam_unix.so no_warn try_first_pass sshd account required pam_unix.so sshd session required pam_permit.so sshd password required pam_permit.so This policy applies to the sshd service (which is not necessarily restricted to the &man.sshd.8; server.) auth, account, session and password are facilities. pam_nologin.so, pam_unix.so and pam_permit.so are modules. It is clear from this example that pam_unix.so and pam_permit.so provide at least two facilities each.

This section has not yet been written.

The PAM API offers six different authentication primitives grouped in four facilities, which are described below. auth Authentication. This facility concerns itself with authenticating the applicant and establishing the account credentials. It provides two primitives: pam_authenticate authenticates the applicant, usually by requesting an authentication token and comparing it with a value stored in a database or obtained from an authentication server. pam_setcred establishes account credentials such as user ID, group membership and resource limits. account Account management. This facility handles 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 a single primitive: pam_acct_mgmt verifies that the requested account is available. session Session management. This facility handles tasks associated with session set-up and tear-down, such as login accounting. It provides two primitives: pam_open_session performs tasks associated with session set-up: add an entry in the utmp and wtmp databases, start an SSH agent, etc. pam_close_session performs tasks associated with session tear-down: add an entry in the utmp and wtmp databases, stop the SSH agent, etc. password Password management. This facility is used to change the authentication token associated with an account, either because it has expired or because the user wishes to change it. It provides a single primitive: pam_chauthtok changes the authentication token, optionally verifying that it is sufficiently hard to guess, has not been used previously, etc.

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 primitives in one or more facilities for one particular mechanism; possible mechanisms for the authentication facility, for instance, include the UNIX password database, NIS, LDAP and Radius. FreeBSD groups all facilities for the same mechanism in one module called pam_mechanism.so (e.g. pam_unix.so.) The original PAM implementation, on the other hand, had separate modules for each facility, called pam_mechanism_facility.so (e.g. pam_unix_auth.so.)

When a server initiates a PAM transaction, the PAM library tries to load a policy for the service specified in the pam_start 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: the possibility for the admin to tune the system security policy (in the wider 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 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 that describes how to interpret the return code from the module. Understanding the control flags is essential to understanding PAM configuration files. There are four different control flags: required Success is required, but the chain continues no matter what this module returns, so that later modules can override it. requisite A negative result from this module will immediately terminate the chain and deny the request. sufficient A positive result from this module will immediately terminate the chain and grant the request. On failure, the chain continues. optional A negative result from this module will be ignored. 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 chain, in the order they are listed, until it reaches the end, or determines that no further processing is necessary (either because a 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 non-optional modules succeeded. 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 and passwords in a directory server could be invoked multiple times with different parameters specifying different directory servers to contact. PAM treat different occurrences of the same module in the same chain as different, unrelated modules.

The lifecycle of a typical PAM transaction is described below. Note that if this any of these steps fails, the server should report a suitable error message to the client and abort the transaction. If necessary, the server obtains arbitrator credentials through a mechanism independent of PAM—most commonly by virtue of having been started by root, or of being setuid root. The server calls pam_start to initialize the PAM library and specify its service name and the target account, and register a suitable conversation function. 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 submits it to PAM using pam_set_item. The server calls pam_authenticate to authenticate the applicant. The server calls pam_acct_mgmt to verify that the requested account is available and valid. The pam_acct_mgmt function will return PAM_NEW_AUTHTOK_REQD if the account's password has expired. If the previous step returned PAM_NEW_AUTHTOK_REQD, the server now calls pam_chauthtok to force the client to change the authentication token for the requested account. Now that the applicant has been properly authenticated, the server calls pam_setcred 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 credentials. Once the correct credentials have been established, the server calls pam_open_session to set up the session. The server now performs whatever service the client requested—for instance, provide the applicant with a shell. Once the server is done serving the client, it calls pam_close_session to tear down the session. Finally, the server calls pam_end 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.

The traditional PAM configuration 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 chain, as shown below: login auth required pam_nologin.so no_warn The fields are, in order: service name, facility name, control flag, module name, and module arguments. Any additional fields are interpreted as additional module arguments. 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, the order in which the individual services and facilities are listed is not—except that entries for the other service, which serves as a fall-back, should come last. The examples in the original PAM paper grouped configuration lines by facility, and Solaris' stock pam.conf still does that, but Linux-PAM (and hence FreeBSD) groups configuration lines by service. Either way is fine; either way makes equal sense. Linux-PAM offers an alternate configuration mechanism, where policies are contained in separate files, named for the service they apply to, in /etc/pam.d/, with only four fields instead of five—the service name field is omitted. In FreeBSD 5.0, starting from mid-January 2002, this is the preferred mechanism. Note, however, that if /etc/pam.conf exists, and contains configuration statements for services which do not have a specific policy in /etc/pam.d/, it will be used as a fall-back for these services. The great advantage of /etc/pam.d/ over /etc/pam.conf is that it is possible to use the same 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 do as follows: &prompt.root; cd /etc/pam.d &prompt.root; ln -s su sudo 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 arbitrary services. One other advantage is that third-party software can easily install policies for their services without the need to edit /etc/pam.conf. Whether you use /etc/pam.conf or /etc/pam.d/, the policy for the special service other is used as a fall-back for any service that does not have its own policy.

As explained in , each line in /etc/pam.conf consists of four or more fields: the service name, the facility name, the control flag, the module name, and zero or more module arguments. 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 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 is specified by the name of the policy file, and omitted from the actual configuration lines, which then start with the facility name. The facility is one of the four facility keywords described in the section. Likewise, the control flag is one of the four keywords described in the section, describing how to interpret 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 this should be avoided as it is non-standard and requires very detailed knowledge of the PAM library to use properly.

This section has not yet been written.

This section has not yet been written.

This section has not yet been written.

This section has not yet been written.

The following is a minimal implementation of &man.su.1; using PAM. Note that it uses the Linux-PAM-specific misc_conv conversation function, which is prototyped in security/pam_misc.h. This section has not yet been written. This is a list of documents relevant to PAM and related issues. It is by no means complete. Samar Vipin Lai Charlie Sun Microsystems The Open Group 1-85912-144-6 June 1997 Morgan Andrew G. October 6, 1999 Sun Microsystems Smørgrav Dag-Erling