From owner-svn-doc-all@freebsd.org Thu Aug 16 14:45:07 2018 Return-Path: Delivered-To: svn-doc-all@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 69AAD1069838; Thu, 16 Aug 2018 14:45:07 +0000 (UTC) (envelope-from bcr@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client CN "mxrelay.nyi.freebsd.org", Issuer "Let's Encrypt Authority X3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 174D185CFB; Thu, 16 Aug 2018 14:45:07 +0000 (UTC) (envelope-from bcr@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id CFE301AD29; Thu, 16 Aug 2018 14:45:06 +0000 (UTC) (envelope-from bcr@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id w7GEj6tf023855; Thu, 16 Aug 2018 14:45:06 GMT (envelope-from bcr@FreeBSD.org) Received: (from bcr@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id w7GEj614023854; Thu, 16 Aug 2018 14:45:06 GMT (envelope-from bcr@FreeBSD.org) Message-Id: <201808161445.w7GEj614023854@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: bcr set sender to bcr@FreeBSD.org using -f From: Benedict Reuschling Date: Thu, 16 Aug 2018 14:45:06 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r52137 - head/en_US.ISO8859-1/articles/pam X-SVN-Group: doc-head X-SVN-Commit-Author: bcr X-SVN-Commit-Paths: head/en_US.ISO8859-1/articles/pam X-SVN-Commit-Revision: 52137 X-SVN-Commit-Repository: doc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.27 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 16 Aug 2018 14:45:07 -0000 Author: bcr Date: Thu Aug 16 14:45:06 2018 New Revision: 52137 URL: https://svnweb.freebsd.org/changeset/doc/52137 Log: Cleanup of this file with regards to overlong lines, bad tag indent, and capitalization in titles as much as possible. Modified: head/en_US.ISO8859-1/articles/pam/article.xml Modified: head/en_US.ISO8859-1/articles/pam/article.xml ============================================================================== --- head/en_US.ISO8859-1/articles/pam/article.xml Thu Aug 16 13:55:09 2018 (r52136) +++ head/en_US.ISO8859-1/articles/pam/article.xml Thu Aug 16 14:45:06 2018 (r52137) @@ -34,9 +34,11 @@ - OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - SUCH DAMAGE. --> -
- Pluggable Authentication Modules - +
+ + Pluggable Authentication Modules This article describes the underlying principles and @@ -53,7 +55,13 @@ - Dag-ErlingSmørgravContributed by + + + Dag-Erling + Smørgrav + + Contributed by + @@ -99,7 +107,7 @@
- Terms and conventions + Terms and Conventions
Definitions @@ -248,27 +256,26 @@
- Usage examples + 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 + Client and Server Are One This simple example shows alice &man.su.1;'ing to root. -&prompt.user; whoami + &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 - +root @@ -283,7 +290,7 @@ root The authentication token is - xi3kiune. + xi3kiune. The arbitrator is root, which is @@ -293,7 +300,7 @@ root
- Client and server are separate + Client and Server Are Separate The example below shows eve try to initiate an &man.ssh.1; connection to @@ -301,7 +308,7 @@ root bob, and succeed. Bob should have chosen a better password! -&prompt.user; whoami + &prompt.user; whoami eve &prompt.user; ssh bob@login.example.com bob@login.example.com's password: god @@ -329,7 +336,7 @@ Welcome to FreeBSD! The authentication token is - god. + god. Although this is not shown in this example, the @@ -339,12 +346,12 @@ Welcome to FreeBSD!
- Sample policy + 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_login_access.so sshd account required pam_unix.so @@ -391,7 +398,7 @@ sshd password required pam_permit.so
Facilities and - primitives + Primitives The PAM API offers six different authentication primitives grouped in four facilities, which are described below. @@ -519,7 +526,8 @@ sshd password required pam_permit.so
- Module Versioning + Module + Versioning FreeBSD's original PAM implementation, based on Linux-PAM, did not use version numbers for PAM modules. @@ -537,15 +545,15 @@ sshd password required pam_permit.so modules. Although &solaris; PAM modules commonly have a version - number, they are not truly versioned, because the number is a - part of the module name and must be included in the + number, they are not truly versioned, because the number is + a part of the module name and must be included in the configuration.
Chains and - policies + Policies When a server initiates a PAM transaction, the PAM library tries to load a policy for the service specified in the @@ -577,8 +585,9 @@ sshd password required pam_permit.so 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. + This control flag was introduced by Sun in &solaris; + 9 (&sunos; 5.9), and is also supported by + OpenPAM. @@ -688,11 +697,11 @@ sshd password required pam_permit.so - The server calls &man.pam.acct.mgmt.3; to verify that the - requested account is available and valid. If the password - is correct but has expired, &man.pam.acct.mgmt.3; will - return PAM_NEW_AUTHTOK_REQD instead of - PAM_SUCCESS. + The server calls &man.pam.acct.mgmt.3; to verify that + the requested account is available and valid. If the + password is correct but has expired, &man.pam.acct.mgmt.3; + will return PAM_NEW_AUTHTOK_REQD + instead of PAM_SUCCESS. @@ -741,18 +750,18 @@ sshd password required pam_permit.so PAM Configuration
- PAM policy files + PAM Policy Files
The - <filename>/etc/pam.conf</filename> file + /etc/pam.conf 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 + 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 @@ -772,7 +781,7 @@ sshd password required pam_permit.so
The - <filename>/etc/pam.d</filename> directory + /etc/pam.d OpenPAM and Linux-PAM support an alternate configuration mechanism, which is the preferred mechanism in FreeBSD. In @@ -796,7 +805,7 @@ sshd password required pam_permit.so su and sudo services, one could do as follows: -&prompt.root; cd /etc/pam.d + &prompt.root; cd /etc/pam.d &prompt.root; ln -s su sudo This works because the service name is determined from @@ -811,27 +820,28 @@ sshd password required pam_permit.so
- The policy search - order + The Policy Search + Order As we have seen above, PAM policies can be found in a number of places. What happens if policies for the same service exist in multiple places? It is essential to understand that PAM's configuration - system is centered on chains. + system is centered on chains.
Breakdown of a - configuration line + Configuration Line - 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. + 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 @@ -845,17 +855,18 @@ sshd password required pam_permit.so facility name. The facility is one of the four facility keywords - described in . + described in . Likewise, the control flag is one of the four keywords - described in , - 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. + described in , 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.
@@ -882,7 +893,8 @@ sshd password required pam_permit.so the following table applies: - PAM chain execution summary + PAM Chain Execution Summary + @@ -891,10 +903,12 @@ sshd password required pam_permit.so - PAM_SUCCESS - PAM_IGNORE + PAM_SUCCESS + PAM_IGNORE other - + @@ -903,24 +917,28 @@ sshd password required pam_permit.so - fail = true; + required - - fail = true; + requisite - - fail = true; break; + sufficient if (!fail) break; - - + optional - @@ -945,22 +963,21 @@ sshd password required pam_permit.so PAM_NEW_AUTHTOK_REQD. The second exception is that &man.pam.setcred.3; treats - binding and - sufficient modules as if they were - required. + binding and sufficient + modules as if they were required. The third and final exception is that &man.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 + in the preliminary phase it treats binding + and sufficient modules as if they were required.
- FreeBSD PAM Modules + FreeBSD PAM + Modules
&man.pam.deny.8; @@ -995,29 +1012,32 @@ sshd password required pam_permit.so
- &man.pam.ftpusers.8; + &man.pam.ftpusers.8; The &man.pam.ftpusers.8; module
- &man.pam.group.8; + &man.pam.group.8; The &man.pam.group.8; module accepts or rejects applicants on the basis of their membership in a particular file group (normally wheel for &man.su.1;). It is - primarily intended for maintaining the traditional behavior - of BSD &man.su.1;, but has many other uses, such as excluding + primarily intended for maintaining the traditional behavior of + BSD &man.su.1;, but has many other uses, such as excluding certain groups of users from a particular service.
- &man.pam.guest.8; + &man.pam.guest.8; The &man.pam.guest.8; module allows guest logins using fixed login names. Various requirements can be placed on the - password, but the default behavior is to allow any password - as long as the login name is that of a guest account. The + password, but the default behavior is to allow any password as + long as the login name is that of a guest account. The &man.pam.guest.8; module can easily be used to implement anonymous FTP logins.
@@ -1035,13 +1055,15 @@ sshd password required pam_permit.so
- &man.pam.lastlog.8; + &man.pam.lastlog.8; The &man.pam.lastlog.8; module
- &man.pam.login.access.8; + &man.pam.login.access.8; The &man.pam.login.access.8; module provides an implementation of the account management primitive which @@ -1050,7 +1072,8 @@ sshd password required pam_permit.so
- &man.pam.nologin.8; + &man.pam.nologin.8; The &man.pam.nologin.8; module refuses non-root logins when /var/run/nologin exists. This file @@ -1066,14 +1089,15 @@ sshd password required pam_permit.so challenge-response mechanism where the response to each challenge is a direct function of the challenge and a passphrase, so the response can be easily computed just - in time by anyone possessing the passphrase, + in time by anyone possessing the passphrase, eliminating the need for password lists. Moreover, since &man.opie.4; never reuses a challenge that has been correctly answered, it is not vulnerable to replay attacks.
- &man.pam.opieaccess.8; + &man.pam.opieaccess.8; The &man.pam.opieaccess.8; module is a companion module to &man.pam.opie.8;. Its purpose is to enforce the restrictions @@ -1091,13 +1115,15 @@ sshd password required pam_permit.so
- &man.pam.passwdqc.8; + &man.pam.passwdqc.8; The &man.pam.passwdqc.8; module
- &man.pam.permit.8; + &man.pam.permit.8; The &man.pam.permit.8; module is one of the simplest modules available; it responds to any request with @@ -1107,19 +1133,22 @@ sshd password required pam_permit.so
- &man.pam.radius.8; + &man.pam.radius.8; The &man.pam.radius.8; module
- &man.pam.rhosts.8; + &man.pam.rhosts.8; The &man.pam.rhosts.8; module
- &man.pam.rootok.8; + &man.pam.rootok.8; The &man.pam.rootok.8; module reports success if and only if the real user id of the process calling it (which is @@ -1130,7 +1159,8 @@ sshd password required pam_permit.so
- &man.pam.securetty.8; + &man.pam.securetty.8; The &man.pam.securetty.8; module
@@ -1161,7 +1191,8 @@ sshd password required pam_permit.so
- &man.pam.tacplus.8; + &man.pam.tacplus.8; The &man.pam.tacplus.8; module
@@ -1182,9 +1213,10 @@ sshd password required pam_permit.so
- PAM Application Programming + PAM Application + Programming - 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.
- Sample PAM Application + Sample PAM + Application The following is a minimal implementation of &man.su.1; using PAM. Note that it uses the OpenPAM-specific &man.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 is a good - starting point, but should not be used in real-world - applications. + 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 is a good starting point, but + should not be used in real-world applications. - + @@ -1245,50 +1279,71 @@ sshd password required pam_permit.so simplified version of OpenPAM's &man.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 are not using OpenPAM, feel free - to download the source code and adapt &man.openpam.ttyconv.3; to - your uses; we believe it to be as robust as a tty-oriented - conversation function can reasonably get. + for real-world use. Even if you are not using OpenPAM, feel + free to download the source code and adapt + &man.openpam.ttyconv.3; to your uses; we believe it to be as + robust as a tty-oriented conversation function can reasonably + get. - Further Reading - + + Further Reading - - This is a list of documents relevant to PAM and related - issues. It is by no means complete. - + + This is a list of documents relevant to PAM and related + issues. It is by no means complete. + Papers - - Making Login Services Independent of Authentication + + Making Login Services Independent of Authentication Technologies - SamarVipin - LaiCharlie + + + Samar + Vipin + + + + + Lai + Charlie + + Sun Microsystems - X/Open - Single Sign-on Preliminary Specification + X/Open + Single Sign-on Preliminary + Specification The Open Group 1-85912-144-6 June 1997 - - Pluggable Authentication Modules - MorganAndrewG. + + Pluggable Authentication Modules + + + Morgan + Andrew + G. + + 1999-10-06 @@ -1297,28 +1352,46 @@ sshd password required pam_permit.so User Manuals - PAM - Administration + PAM + Administration Sun Microsystems - Related Web pages + Related Web Pages - OpenPAM homepage - SmørgravDag-Erling + OpenPAM + homepage + + + Smørgrav + Dag-Erling + + ThinkSec AS - Linux-PAM homepage - MorganAndrewG. + Linux-PAM + homepage + + + Morgan + Andrew + G. + + - Solaris PAM homepage + Solaris + PAM homepage Sun Microsystems