18.1. About

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.

18.2. Introduction

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 primarily on FreeBSD 5.x and
NetBSD 3.x, which 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™.

18.3. Terms and conventions

18.3.1. Definitions

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.

18.3.2. 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 policy applies to the sshd
service (which is not necessarily restricted to the
sshd(8) server.)

auth, account,
session and
password are facilities.

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 provides at least two
facilities (authentication and account
management.)

There are some differences between FreeBSD and NetBSD PAM
policies:

By default, every configuration is done
under /etc/pam.d.

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.

For authentication, NetBSD forces at least one
required, requisite or
binding module to be present.

18.4. PAM Essentials

18.4.1. Facilities and
primitives

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(3) 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(3) 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:

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(3) changes the authentication
token, optionally verifying that it is sufficiently
hard to guess, has not been used previously,
etc.

18.4.2. Modules

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.

18.4.2.1. Module Naming

FreeBSD and NetBSD implement each mechanism in a single module,
named
pam_mechanism.so
(for instance, pam_unix.so for the UNIX®
mechanism.) Other implementations sometimes have separate
modules for separate facilities, and 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 used to authenticate dialup users.
Also, almost every module has a man page with the same name,
i.e.: pam_unix(8) explains how the
pam_unix.so module works.

18.4.2.2. Module Versioning

FreeBSD's original PAM implementation, based on
Linux-PAM, did not use version numbers for PAM modules.
This would commonly cause problems with legacy 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 modules.

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 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 built)
applications to take advantage of the most recent
modules.

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 in the
configuration.

18.4.2.3. Module Path

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
/usr/lib/security.

18.4.3. Chains and
policies

When a server initiates a PAM transaction, the PAM library
tries to load a policy for the service specified in the
pam_start(3) 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 a number of
different control flags:

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 the module fails, the
rest of the chain is executed, but the request is
ultimately denied.

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 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.

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 chain is
immediately terminated and the request is denied.

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 the module fails, the
module is ignored and the rest of the chain is
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.

optional

The module is executed, but its result is ignored.
If all modules in a chain are marked
optional, all requests will always be
granted.

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
binding or
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.

18.4.4. Transactions

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 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(3) 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(3).

The server calls pam_acct_mgmt(3) to verify that the
requested account is available and valid. If the password
is correct but has expired, pam_acct_mgmt(3) will
return PAM_NEW_AUTHTOK_REQD instead of
PAM_SUCCESS.

If the previous step returned
PAM_NEW_AUTHTOK_REQD, the server now
calls pam_chauthtok(3) 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(3) 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(3) to set up the
session.

The server now performs whatever service the client
requested—for instance, provide the applicant with a
shell.

Finally, the server calls pam_end(3) 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.

18.5. PAM Configuration

18.5.1. PAM policy files

18.5.1.1. The
/etc/pam.conf file

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 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. The 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 groups configuration lines by service.
Either way is fine; either way makes equal sense.

18.5.1.2. The
/etc/pam.d directory

OpenPAM and Linux-PAM support an alternate configuration
mechanism, which is the 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. These files
are stored in /etc/pam.d/.

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 line from the previous
section, one would have the following line in
/etc/pam.d/login:

auth required pam_nologin.so no_warn

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. For
instance, to use the same policy for the
su and sudo services,
one could do as follows:

#cd /etc/pam.d#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 multiple differently-named
services.

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 packages.

18.5.1.3. The policy search
order

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 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.

It is essential to understand that PAM's configuration
system is centered on chains.

18.5.2. Breakdown of a
configuration line

As explained in the 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 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.

Likewise, the control flag is one of the four keywords
described in the Chains and
policies 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 closely tied
in with the way Linux-PAM dispatches service calls (which
differs greatly from the way Solaris™ and OpenPAM do it.)
Unsurprisingly, OpenPAM does not support this syntax.

18.5.3. Policies

To configure PAM correctly, it is essential to understand
how policies are interpreted.

When an application calls pam_start(3), 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, the corresponding chains
from the policy for the other service are
substituted.

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 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 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 following table applies:

Table 18.1. PAM chain execution summary

PAM_SUCCESS

PAM_IGNORE

other

binding

if (!fail) break;

-

fail = true;

required

-

-

fail = true;

requisite

-

-

fail = true; break;

sufficient

if (!fail) break;

-

-

optional

-

-

-

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. Otherwise, it returns
PAM_SUCCESS.

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 returned PAM_NEW_AUTHTOK_REQD, the
dispatcher will return
PAM_NEW_AUTHTOK_REQD.

The second exception is that pam_setcred(3) treats
binding and
sufficient modules as if they were
required.

The third and final exception is that
pam_chauthtok(3) 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
sufficient modules as if they were
required.

18.6. PAM modules

18.6.1. Common Modules

The pam_deny(8) 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 of every chain), or for
terminating chains of sufficient
modules.

The pam_echo(8) 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 to display messages such as
“Unauthorized access will be prosecuted” before
starting the authentication procedure.

The pam_exec(8) 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
possible application is to use it to run a program at login
time which mounts the user's home directory.

The pam_ftpusers(8) 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 ftpd(8), but this will be fixed in
the future.

The pam_group(8) module accepts or rejects applicants
on the basis of their membership in a particular file group
(normally wheel for su(1)). It is
primarily intended for maintaining the traditional behaviour
of BSD su(1), but has many other uses, such as excluding
certain groups of users from a particular service.

In NetBSD, there is an argument called
authenticate in which the user is asked to
authenticate using his own password.

The pam_guest(8) 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 long as the login name is that of a guest account. The
pam_guest(8) module can easily be used to implement
anonymous FTP logins.

The pam_krb5(8) 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 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 a credential cache and the environment variable
KRB5CCNAME is set appropriately. The credentials cache should be
destroyed by the user at logout with kdestroy(1).

The pam_permit(8) 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 chains would otherwise be
empty.

The pam_rhosts(8) 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 /etc/hosts.equiv or in the
target user's ~/.rhosts.

The pam_rootok(8) 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
non-networked services such as su(1) or passwd(1),
to which the root should have automatic
access.

The pam_self(8) 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
su(1), where the identity of the applicant can be easily
verified.

The pam_ssh(8) module provides both authentication
and session services. The authentication service allows users
who have passphrase-protected SSH secret keys in their
~/.ssh directory to authenticate
themselves by typing their passphrase. The session service
starts ssh-agent(1) 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
xdm(1) or another PAM-aware X login manager) or at the
console.

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, encrypted session, etc.),
otherwise the user's SSH passphrase could be compromised.

Additional consideration should be given to the use of
pam_ssh(8). 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 effective
means of enforcing SSH passphrase quality, this has the potential
to expose the system to security risks.

The pam_unix(8) module implements traditional UNIX®
password authentication, using getpwnam(3) under FreeBSD
or getpwnam_r(3) 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 (enforcing account and password expiration times) and
password-changing 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.

18.6.2. NetBSD-specific PAM Modules

The pam_skey(8) module implements S/Key One Time
Password (OTP) authentication methods, using the
/etc/skeykeys database.

18.7. PAM Application Programming

This section has not yet been written.

18.8. PAM Module Programming

This section has not yet been written.

18.9. Sample PAM Application

The following is a minimal implementation of su(1)
using PAM. Note that it uses the OpenPAM-specific
openpam_ttyconv(3) 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 to provide your own conversation function. A
robust conversation function is surprisingly difficult to
implement; the one presented in the
Sample PAM Conversation
Function sub-chapter is a good
starting point, but should not be used in real-world
applications.

18.10. Sample PAM Module

The following is a minimal implementation of
pam_unix(8), offering only authentication services. It
should build and run with most PAM implementations, but takes
advantage of OpenPAM extensions if available: note the use of
pam_get_authtok(3), which enormously simplifies prompting
the user for a password.

18.11. Sample PAM Conversation
Function

The conversation function presented below is a greatly
simplified version of OpenPAM's openpam_ttyconv(3). 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 use. Even if you're not using OpenPAM, feel free
to download the source code and adapt openpam_ttyconv(3) to
your uses; we believe it to be as robust as a tty-oriented
conversation function can reasonably get.