From 9dc2ba6133b59edbef7fd3751e2e74ebf843218d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dag-Erling=20Sm=C3=B8rgrav?= Date: Sat, 12 Jan 2002 20:42:39 +0000 Subject: [PATCH] Lots more text, and some markup and whitespace fixes. --- en_US.ISO8859-1/articles/pam/article.sgml | 360 ++++++++++++++++------ 1 file changed, 268 insertions(+), 92 deletions(-) diff --git a/en_US.ISO8859-1/articles/pam/article.sgml b/en_US.ISO8859-1/articles/pam/article.sgml index 59d258f12b..e3d0553e10 100644 --- a/en_US.ISO8859-1/articles/pam/article.sgml +++ b/en_US.ISO8859-1/articles/pam/article.sgml @@ -66,7 +66,7 @@ FreeBSD Entities//EN"> %freebsd; - +
Introduction The Pluggable Authentication Modules (PAM) library is a @@ -84,31 +84,31 @@ FreeBSD Entities//EN"> %freebsd; 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 + 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 - - Definitions - +
+ 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 @@ -124,6 +124,14 @@ FreeBSD Entities//EN"> %freebsd; PAM. + + account + + The set of credentials the applicant is requesting + from the arbitrator. + + + applicant @@ -223,14 +231,6 @@ FreeBSD Entities//EN"> %freebsd; - - account - - The set of credentials the applicant is requesting - from the arbitrator. - - - token @@ -250,21 +250,21 @@ FreeBSD Entities//EN"> %freebsd; - +
- +
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` @@ -295,9 +295,9 @@ root why &man.su.1; is setuid root. - +
- +
Client and server are separate The example below shows eve try to @@ -305,7 +305,7 @@ root 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 @@ -341,14 +341,14 @@ Welcome to FreeBSD! 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_unix.so no_warn try_first_pass sshd account required pam_unix.so @@ -360,7 +360,7 @@ sshd password required pam_permit.so This policy applies to the sshd service (which is not necessarily restricted to the - &man.sshd.8; server). + &man.sshd.8; server.) auth, account, @@ -377,28 +377,29 @@ sshd password required pam_permit.so facilities each. - - +
+
- +
Conventions This section is intentionally left blank. - - +
+
- +
PAM Essentials - - Facilities and primitives +
+ Facilities and + primitives The PAM API offers six different authentication primitives grouped in four facilities, which are described below. - auth + auth Authentication. This facility concerns itself with authenticating the applicant and @@ -422,9 +423,9 @@ sshd password required pam_permit.so - + - account + account Account management. This facility handles non-authentication-related issues of @@ -440,9 +441,9 @@ sshd password required pam_permit.so - + - session + session Session management. This facility handles tasks associated with session set-up @@ -468,9 +469,9 @@ sshd password required pam_permit.so - + - password + password Password management. This facility is used to change the authentication token @@ -489,10 +490,10 @@ sshd password required pam_permit.so - - - +
+ +
Modules Modules are a very central concept in PAM; after all, @@ -504,29 +505,188 @@ sshd password required pam_permit.so 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. - + 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.) +
- - Chains and policies - - Explain chains and policies - +
+ 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 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're 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. +
+ +
Transactions - - Describe a transaction from start to finish - - - + The lifecycle of a typical PAM transaction goes like + this: + + + + 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. If + pam_authenticate returns something + else than PAM_SUCCESS or + PAM_NEW_AUTHTOK_REQD, it notifies the + client that the request was denied, and aborts the + transaction. + + + + 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. If this fails, the server aborts the + transaction. + + + + The server calls pam_acct_mgmt to + verify that the requested account is available. If this + fails, the server aborts the transaction. + + + + 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 alls + 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. + + +
+
+ +
PAM Configuration - +
Location of configuration files The traditional PAM configuration file is @@ -557,8 +717,8 @@ sshd password required pam_permit.so 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 + 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 @@ -587,9 +747,9 @@ sshd password required pam_permit.so /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 @@ -609,38 +769,54 @@ sshd password required pam_permit.so facility name. The facility is one of the four facility keywords - described in the chapter. - + 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. +
+ +
Policies - - +
+
- +
PAM Modules This chapter briefly documents the various PAM modules that exist in FreeBSD. - +
- +
PAM Application Programming This chapter describes how to integrate PAM into your application. - +
- +
PAM Module Programming This chapter describes how to write PAM modules. - - - +
+ + + Sample PAM application + + Source code for a minimal &man.su.1; workalike + + + Further Reading This is a list of documents relevant to PAM and related @@ -649,10 +825,10 @@ sshd password required pam_permit.so - Making Login Services Independent of Authentication - Technologies—the original PAM whitepaper from - Sun. + url="http://www.sun.com/software/solaris/pam/pam.external.pdf"> + Making Login Services Independent of Authentication + Technologies—the original PAM whitepaper from + Sun. url="http://www.opengroup.org/pubs/catalog/p702.htm"> 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). + download the text version, or buy the paper version.) by Andrew G. Morgan, author of Linux-PAM. - +