Pluggable Authentication Modules Dag-Erling Smørgrav Revision: d8432b1e37 Copyright © 2001, 2002, 2003 Networks Associates Technology, Inc. This article was written for the FreeBSD Project by ThinkSec AS and Network Associates Lab- oratories, the Security Research Division of Network Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 (“CBOSS”), as part of the DARPA CHATS research program. FreeBSD is a registered trademark of the FreeBSD Foundation. Linux is a registered trademark of Linus Torvalds. Motif, OSF/1, and UNIX are registered trademarks and IT DialTone and The Open Group are trademarks of The Open Group in the United States and other countries. Sun, Sun Microsystems, Java, Java Virtual Machine, JDK, JRE, JSP, JVM, Netra, OpenJDK, Solaris, StarOffice, SunOS and VirtualBox are trademarks or registered trademarks of Sun Microsys- tems, Inc. in the United States and other countries. Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this document, and the FreeBSD Project was aware of the trademark claim, the designations have been followed by the “™” or the “®” symbol. Abstract This article describes the underlying principles and mechanisms of the Pluggable Authenti- cation Modules (PAM) library, and explains how to configure PAM, how to integrate PAM into applications, and how to write PAM modules. Table of Contents 1. Introduction ........................................................................................................................... 1 2. Terms and Conventions ............................................................................................................. 2 3. PAM Essentials ........................................................................................................................ 4 4. PAM Configuration ................................................................................................................... 6 5. FreeBSD PAM Modules .............................................................................................................. 8 6. PAM Application Programming .................................................................................................. 10 7. PAM Module Programming ....................................................................................................... 10 A. Sample PAM Application .......................................................................................................... 11 B. Sample PAM Module ............................................................................................................... 14 C. Sample PAM Conversation Function ........................................................................................... 16 Further Reading ........................................................................................................................ 18 1. 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 les. Terms and Conventions 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, which uses OpenPAM, it should be equally applicable to FreeBSD 4.x, which uses Linux-PAM, and other operating systems such as Linux and Solaris™. 2. Terms and Conventions 2.1. Definitions The terminology surrounding PAM is rather confused. Neither Samar and Lai's original paper nor the XSSO spec- ification 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 rst attempt at es- tablishing 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: authentica- tion, account management, session management and authentication token update. module A collection of one or more related functions implementing a particular au- thentication facility, gathered into a single (normally dynamically loadable) binary le 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. 2 Pluggable Authentication Modules 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. 2.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. 2.2.1. Client and Server Are One This simple example shows alice su(1)'ing to root. % whoami alice % ls -l `which su` -r-sr-xr-x 1 root wheel 10744 Dec 6 19:06 /usr/bin/su % su - Password: xi3kiune # whoami root • The applicant is alice. • The account is root. • The su(1) process is both client and server. • The authentication token is xi3kiune. • The arbitrator is root, which is why su(1) is setuid root. 2.2.2. Client and Server Are Separate The example below shows eve try to initiate an ssh(1) connection to login.example.com, ask to log in as bob, and succeed. Bob should have chosen a better password! % whoami eve % ssh [email protected] [email protected]'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! % • The applicant is eve. • The client is Eve's ssh(1) process. • The server is the 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. 3 PAM Essentials 2.2.3. Sample Policy 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_login_access.so sshd account required pam_unix.so sshd session required pam_lastlog.so no_fail sshd password required pam_permit.so • 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 manage- ment.) 3. PAM Essentials 3.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 cre- dentials. It provides two primitives: • pam_authenticate(3) authenticates the applicant, usually by requesting an authentication token and com- paring 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.