diff --git a/en_US.ISO8859-1/articles/pam/article.sgml b/en_US.ISO8859-1/articles/pam/article.sgml index fe80a172eb..8fb95496e2 100644 --- a/en_US.ISO8859-1/articles/pam/article.sgml +++ b/en_US.ISO8859-1/articles/pam/article.sgml @@ -1,419 +1,644 @@ %man; %freebsd; %newsgroups; %authors; %mailing-lists; ]>
Pluggable Authentication Modules $FreeBSD$ 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 - Introduction + 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 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. Trademarks 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. - Terms and conventions + Terms and conventions 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. 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. - target + account - The user or entity whose credentials the applicant - is requesting. + The set of credentials the applicant is requesting + from the arbitrator. token - A chunk of information associated with the target, + 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. Usage 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 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; +&prompt.root; whoami +root The applicant is alice. - The target is root. + 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. Client and server are separate - The example below shows alice try to + 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 target is bob. + The account is bob. The authentication token is god. Although this is not shown in this example, the arbitrator is root. Sample policy The following is FreeBSD's default policy for sshd: -sshd auth required pam_nologin.so no_warn +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 +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. Conventions This section is intentionally left blank. - PAM Essentials + PAM Essentials + + + Facilities and primitives - This section describes the central concepts of PAM. + 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 + + Modules are a very central concept in PAM; after all, + they're 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. The + original PAM implementation, on the other hand, had separate + modules for each facility, called + pam_mechanism_facility.so. + + + + Chains and policies + + Explain chains and policies + + + + Transactions + + Describe a transaction from start to finish + - PAM Configuration + PAM Configuration - This section describes how to configure PAM on - FreeBSD. + + Location of configuration files + + 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-December + 2001, 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. + + + + Breakdown of a configuration line + + As explained in the previous 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're + 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 chapter. + + + + Policies + + + - PAM Modules + PAM Modules - This section briefly documents the various PAM modules that + This chapter briefly documents the various PAM modules that exist in FreeBSD. - PAM Application Programming + PAM Application Programming - This section describes how to integrate PAM into your + This chapter describes how to integrate PAM into your application. - PAM Module Programming + PAM Module Programming - This section describes how to write PAM modules. + This chapter describes how to write PAM modules. - Further Reading + Further Reading This is a list of documents relevant to PAM and related issues. It is by no means complete. Making Login Services Independent of Authentication Technologies—the original PAM whitepaper from Sun. PAM Administration—an introduction to configuring and using PAM, from Sun. X/Open Single Sign-on Preliminary Specification (OpenGroup members can get the PDF; others will have to register to download the text version, or buy the paper version). Pluggable Authentication Modules—a whitepaper by Andrew G. Morgan, author of Linux-PAM.