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 .