Page MenuHomeFreeBSD
Files F160350505

D32530.diff
No OneTemporary
Actions

D32530.diff
View Options

Index: contrib/openpam/doc/man/pam.8
===================================================================
--- /dev/null
+++ contrib/openpam/doc/man/pam.8
@@ -0,0 +1,583 @@
+.\" Copyright © 2001-2003 Networks Associates Technology, Inc.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd October 16, 2021
+.Dt pam 8
+.Os
+.Nm pam
+.Nd "Pluggable Authentication Modules (PAM)"
+.Sh SYNOPSIS
+This man page describes the underlying principles and mechanisms of
+the Pluggable Authentication Modules
+.Pq PAM
+library, and how to configure PAM.
+.Pp
+The 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.
+.Sh DESCRIPTION
+Definitions of terms for actors and entities involved in PAM:
+.Bl -tag -width "transaction"
+.It account
+The set of credentials the applicant is requesting from the arbitrator.
+.It applicant
+The user or entity requesting authentication.
+.It 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.
+.It 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.
+.It client
+The application responsible for initiating an authentication request
+on behalf of the applicant and for obtaining the necessary
+authentication information from them.
+.It facility
+One of the four basic groups of functionality provided by PAM:
+authentication, account management, session management, and
+authentication token update.
+.It module
+A collection of one or more related functions implementing a
+particular authentication facility, gathered into a single
+.Pq normally dynamically loadable
+binary file and identified by a single name.
+.It 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.
+.It 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.
+.It 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.
+.It 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.
+.It token
+A chunk of information associated with the account, such as
+a password or passphrase, which the applicant must provide to
+prove their identity.
+.It 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.
+.El
+.Sh EXAMPLES
+.Ss Client and Server Are One
+This example shows the user alice
+.Xr su 1
+to root.
+.Bd -literal
+% whoami
+alice
+
+% ls -l `which su`
+-r-sr-xr-x 1 root wheel 17232 Apr 8 2021 /usr/bin/su
+
+% su -
+Password: xi3kune
+# whoami
+root
+.Ed
+.Pp
+.Bl -bullet -compact
+.It
+The applicant is
+.Li alice .
+.It
+The account is
+.Li root .
+.It
+The
+.Xr su 1
+process is both client and server.
+.It
+The authentication token is
+.Li xi3kiune .
+.It
+The arbitrator is
+.Li root ,
+which is why
+.Xr su 1
+is setuid
+.Li root .
+.El
+.Ss Client and Server Are Separate
+The example below shows
+.Li eve
+try to initiate an
+.Xr ssh 1
+connection to
+.Li login.example.com ,
+ask to log in as
+.Li bob ,
+and succeed.
+Bob should have chosen a better password!
+.Bd -literal
+% whoami
+eve
+
+% ssh bob@login.example.com
+bob@login.example.com's password:
+% god
+Last login: Fri Oct 15 16:34:47 2021 from 192.168.0.1
+FreeBSD 13.0-RELEASE-p4 (GENERIC) #0: Tue Aug 24 07:33:27 UTC 2021
+
+Welcome to FreeBSD!
+%
+.Ed
+.Pp
+.Bl -bullet -compact
+.It
+The applicant is
+.Li eve .
+.It
+The client is Eve's
+.Xr ssh 1
+process.
+.It
+The server is the
+.Xr sshd 8
+process on
+.Li login.example.com .
+.It
+The account is
+.Li bob .
+.It
+The authentication token is
+.Li god .
+.It
+Although it is not shown in this example, the arbitrator is
+.Li root .
+.El
+.Ss Sample Policy
+The following is
+.Fx Ns 's
+default policy for
+.Dv sshd .
+.Pp
+.Bd -literal
+auth sufficient pam_opie.so no_warn no_fake_prompts
+auth requisite pam_opieaccess.so no_warn allow_local
+auth required pam_unix.so no_warn try_first_pass
+account required pam_nologin.so
+account required pam_login_access.so
+account required pam_unix.so
+session required pam_permit.so
+password required pam_unix.so no_warn try_first_pass
+.Ed
+.Pp
+.Bl -bullet -compact
+.It
+This policy applies to the
+.Dv sshd
+service
+.Po
+which is not neccessarily restricted to the
+.Xr sshd 8
+server.
+.Pc
+.It
+.Dv auth ,
+.Dv account ,
+.Dv session ,
+and
+.Dv password
+are facilities.
+.It
+pam_nologin.so, pam_unix.so, pam_login_access.so, pam_lastlog.so,
+and pam_permit.so are modules.
+From this example we can see that pam_unix.so provides at least
+two facilities
+.Pq authentication and account management.
+.El
+.Sh PAM ESSENTIALS
+.Ss Facilities and Primitives
+The PAM API offers six different authentication primitives grouped
+in four facilities, which are described below.
+.Bl -tag -width "password"
+.It auth
+.Em Authentication .
+This facility concerns itself with authenticating the applicant
+and establishing the account credentials.
+It contains two primitives:
+.Bl -bullet
+.It
+.Xr 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.
+.It
+.Xr pam_setcred 3
+establishes account credentials such as user ID, group membership,
+and resource limits.
+.El
+.It account
+.Em 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:
+.Bl -bullet
+.It
+.Xr pam_acct_mgmt 3
+verifies that the requested account is available.
+.El
+.It session
+.Em Session management .
+This facility handles tasks associated with session set-up and
+tear-down, such as login accounting.
+It provides two primitives:
+.Bl -button
+.It
+.Xr pam_open_session 3
+performs tasks associated with session set-up: add an entry in the
+utmp and wtmp databases, start an SSH agent, and so on.
+.It
+.Xr pam_close_session 3
+performs tasks associated with session tear-down: add an entry
+in the utmp and wtmp databases, stop the SSH agent, and so on.
+.El
+.It password
+.Em 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:
+.Bl -bullet
+.It
+.Xr pam_chauthtok 3
+changes the authentication token, optionally verifying that it is
+sufficiently hard to guess, has not been used previously, and so on.
+.El
+.El
+.Ss Modules
+Modules are a very central concept in PAM; after all, they are the
+.Dq M
+in
+.Dq 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.
+Examples of possible mechanisms for the authentication facility
+include the
+.Ux
+password database, NIS, LDAP, and Radius.
+.Pp
+.Em Module Naming .
+FreeBSD implements each mechanism in a single module, named
+.Li pam_mechanism.so
+.Po
+for instance,
+.Li pam_unix.so
+for the
+.Ux
+mechanism.
+.Pc
+Other implementations sometimes have separate modules for separate
+facilities, and include the facility name as well as mechanism name
+in the module name.
+One example of this, Solaris, has a
+.Li pam_dial_auth.so.1
+module which is commonly used to authenticate dial-up users.
+.Pp
+.Em Chains and Policies .
+When a server initiates a PAM transaction, the PAM library tries to
+load a policy for the service specified in the
+.Xr pam_start 3
+call.
+The policy specifies how authentication requests should be processed,
+and is defined in a configuration file.
+This is the central concept in PAM; the possibility for the admin to
+tune the system security policy
+.Pq in the wider sense of the word
+simply by editing a text file.
+.Pp
+A policy consists of four chains, one for each of the four PAM
+facilities.
+Each chain is a sequence of configuration statements which specify
+a module to invoke, some
+.Pq optional
+parameters to pass to the module, and a control flag that describes
+how to interpret the return code from the module.
+.Pp
+Understanding the control flags is essential to understanding PAM
+configuration files.
+There are four different control flags:
+.Bl -tag -width "sufficient"
+.It 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.
+.Pp
+This control flag was introduced by Sun in Solaris 9
+.Pq SunOS 5.9 ,
+and is also supported by OpenPAM.
+.It 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.
+.It 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.
+.It 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.
+.Pp
+The semantics of this flag may be confusing, especially when
+it is the last module in a chain.
+The current recommendation is to use the
+.Li binding
+control flag instead.
+.It optional
+The module is executed, but its result is ignored.
+If all modules in a chain are marked
+.Li optional ,
+all requests will always be granted.
+.El
+.Pp
+When a server invokes one of the six PAM primitives, PAM retrieves
+the chain for the facility the primitive belongs to,
+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
+.Po
+either because a
+.Li binding
+or
+.Li sufficient
+module succeeded, or because a
+.Li requisite
+module failed.
+.Pc
+The request is granted if and only if at least one module was
+invoked, and all non-optional modules succeeded.
+.Pp
+It is possible, though not very common, to have the same module
+listed multiple times in the same chain.
+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 treats different occurrences of the same module in the same
+chain as different, unrelated modules.
+.Ss 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.
+.Bl -enum
+.It
+If necessary, the server obtains arbitrator credentials through a
+mechanism independent of PAM.
+Often this is because the server was started by
+.Li root ,
+or the server is setuid
+.Li root .
+.It
+The server calls
+.Xr pam_start 3
+to initialize the PAM library and specify its service name,
+specify the target account, and register a suitable conversation
+function.
+.It
+The server obtains various information relating to the transaction
+.Po
+such as the applicant's user name and the name of the host the
+client runs on
+.Pc
+and submits it to PAM using
+.Xr pam_set_item 3 .
+.It
+The server calls
+.Xr pam_authenticate 3
+to authenticate the applicant.
+.It
+The server calls
+.Xr pam_acct_mgmt 3
+to verify that the requested account is available and valid.
+If the password is correct but has expired,
+.Xr pam_acct_mgmt 3
+will return
+.Dv PAM_NEW_AUTHTOK_REQD
+instead of
+.Dv PAM_SUCCESS .
+.It
+If the previous step returned
+.Dv PAM_NEW_AUTHTOK_REQD ,
+the server now calls
+.Xr pam_chkauthtok 3
+to force the client to change the authentication token for the
+requeted account.
+.It
+Now that the applicant has been properly authenticated,
+the server calls
+.Xr pam_setcred 3
+to estabilsh 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.
+.It
+Once the correct credentials have been established, the server calls
+.Xr pam_open_session 3
+to set up the session.
+.It
+The server performs whatever service the client requested.
+One example is providing the applicant with a shell.
+.It
+Once the server is done serving the client, it calls
+.Xr pam_close_session 3
+to tear down the session.
+.It
+Finally, the server calls
+.Xr 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.
+.El
+.Sh PAM CONFIGURATION
+.Ss PAM Policy Files
+.Em Pa /etc/pam.conf .
+The traditional PAM policy file is
+.Pa /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:
+.Bd -literal
+login auth required pam_nologin.so no_warn
+.Ed
+.Pp
+The fields are, in order: service name, facility name, control flag,
+and module arguments.
+Any additional fields are interpreted as additional module arguments.
+.Pp
+A separate chain is constructed for each service / facility pair,
+so while the order in which lines for the same facility appear is
+significant, the order in which the individual services and
+facilities are not.
+The examples in the original PAM paper groupd configuration lines
+by facility, and the Solaris stock
+.Pa pam.conf
+still does that, but
+.Fx Ns 's
+stock configuration groups configuration lines by service.
+Either way is fine; either way makes equal sense.
+.Pp
+.Em Pa /etc/pam.d
+In
+.Fx ,
+the preferred mechanism to configure policy files is for each
+policy to be contained in a separate file bearing the name
+of the service it applies to.
+These files are stored in
+.Pa /etc/pam.d/ .
+.Pp
+These per-service policy files have only four fields instead of
+five for
+.Pa /etc/pam.conf ,
+because the service name is omitted.
+Instead of the simple
+.Pa pam.conf
+line from the previous section, one would have the following line in
+.Pa /etc/pam.d/login :
+.Bd -literal
+auth required pam_nologin.so no_warn
+.Ed
+.Pp
+As a consequence of this simplified syntax, it is possible to use
+the same policy for multiple services by linking each service name
+to the same policy file.
+To use the same policy file for the
+.Li su
+and
+.Li sudo
+services, one could do as follows:
+.Bd -literal
+# cd /etc/pam.d
+# ln -s su sudo
+.Ed
+.Pp
+This works because the service name is determined from the file name
+instead of being specified in the policy file, so the same file can
+be used for multiple differently-named services.
+.Pp
+Since each service's policy is stored in a separate file, the
+.Pa pam.d
+mechanism makes it very easy to install additional policies for
+third-party software packages.
+.Pp
+PAM configuration syntax and the policy search order are described in
+.Xr pam.conf 5
+in more detail.
+.Sh SEE ALSO
+.Xr pam 3 ,
+.Xr pam.conf 5 ,
+.Xr pam_deny 8 ,
+.Xr pam_echo 8 ,
+.Xr pam_exec 8 ,
+.Xr pam_ftpusers 8 ,
+.Xr pam_group 8 ,
+.Xr pam_guest 8 ,
+.Xr pam_krb5 8 ,
+.Xr pam_ksu 8 ,
+.Xr pam_lastlog 8 ,
+.Xr pam_login_access 8 ,
+.Xr pam_nologin 8 ,
+.Xr pam_opie 8 ,
+.Xr pam_opieaccess 8 ,
+.Xr pam_passwdqc 8 ,
+.Xr pam_permit 8 ,
+.Xr pam_radius 8 ,
+.Xr pam_rhosts 8 ,
+.Xr pam_rootok 8 ,
+.Xr pam_securetty 8 ,
+.Xr pam_self 8 ,
+.Xr pam_ssh 8 ,
+.Xr pam_tacplus 8 ,
+.Xr pam_unix 8
+.Pp
+This manual page was based heavily on an article by Dag-Erling Smørgrav,
+.Lk https://docs.freebsd.org/en/articles/pam/ "Pluggable Authentication Modules" .
+.Sh STANDARDS
+.Rs
+.%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules"
+.%D "June 1997"
+.Re
+.Sh AUTHORS
+The OpenPAM library was developed for the
+.Fx
+Project by ThinkSec AS and Network Associates Laboratories, the
+Security Research Division of Network Associates, Inc.\& under
+DARPA/SPAWAR contract N66001-01-C-8035
+.Pq Dq CBOSS ,
+as part of the DARPA CHATS research program.
+.Pp
+The OpenPAM library is maintained by
+.An Dag-Erling Sm\(/orgrav Aq Mt des@des.no .
+.Pp
+This man page was transcribed by
+.An Felix Johnson
+.Aq Mt felix.the.red@gmail.com .
+.Sh HISTORY
+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 been
+adopted as a standard.
+.Pp
+.Fx has used OpenPAM since
+.Fx 5.0 .

File Metadata

Mime Type
text/plain
Expires
Wed, Jun 24, 2:04 PM (21 h, 25 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
34272124
Default Alt Text
D32530.diff (17 KB)

Event Timeline