diff --git a/en_US.ISO8859-1/articles/pam/Makefile b/en_US.ISO8859-1/articles/pam/Makefile index a7906eff2e..d19510ec77 100644 --- a/en_US.ISO8859-1/articles/pam/Makefile +++ b/en_US.ISO8859-1/articles/pam/Makefile @@ -9,13 +9,16 @@ INSTALL_ONLY_COMPRESSED?= JADEFLAGS+= -V %generate-article-toc% -SRCS= article.sgml pam_app.c pam_module.c +SRCS= article.sgml pam_app.c pam_conv.c pam_module.c -CLEANFILES+= pam_app.c pam_module.c +CLEANFILES+= pam_app.c pam_conv.c pam_module.c pam_app.c: su.c sed -e '/^[\/ ]\*/d' ${.ALLSRC} >${.TARGET} +pam_conv.c: converse.c + sed -e '/^[\/ ]\*/d' ${.ALLSRC} >${.TARGET} + pam_module.c: pam_unix.c sed -e '/^[\/ ]\*/d' ${.ALLSRC} >${.TARGET} diff --git a/en_US.ISO8859-1/articles/pam/article.sgml b/en_US.ISO8859-1/articles/pam/article.sgml index b857797f41..9221ab2494 100644 --- a/en_US.ISO8859-1/articles/pam/article.sgml +++ b/en_US.ISO8859-1/articles/pam/article.sgml @@ -76,13 +76,13 @@ At the time of this 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. + Although this article focuses primarily on FreeBSD 5.x, + which uses OpenPAM, it should be equally applicable to FreeBSD + 4.x, which uses Linux-PAM, and other operating systems such as + Linux and Solaris. -
- Trademarks +
+ Trademarks Sun, Sun Microsystems and Solaris are trademarks or registered trademarks of Sun Microsystems, Inc. @@ -245,8 +245,8 @@
-
- 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 @@ -342,11 +342,14 @@ Welcome to FreeBSD! 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 -sshd session required pam_permit.so -sshd password required pam_permit.so + +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 +sshd session required pam_lastlog.so no_fail +sshd password required pam_permit.so + @@ -362,19 +365,21 @@ sshd password required pam_permit.so pam_nologin.so, - pam_unix.so and + pam_unix.so, + pam_login_access.so, + pam_lastlog.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. + pam_unix.so provides at least two + facilities (authentication and account + management.)
-
- Conventions +
+ Conventions This section has not yet been written.
@@ -401,17 +406,17 @@ sshd password required pam_permit.so - 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. + &man.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. - pam_setcred establishes - account credentials such as user ID, group - membership and resource limits. + &man.pam.setcred.3; establishes account + credentials such as user ID, group membership and + resource limits. @@ -428,8 +433,8 @@ sshd password required pam_permit.so - pam_acct_mgmt verifies that - the requested account is available. + &man.pam.acct.mgmt.3; verifies that the + requested account is available. @@ -445,17 +450,17 @@ sshd password required pam_permit.so - pam_open_session performs - tasks associated with session set-up: add an entry - in the utmp and + &man.pam.open.session.3; 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 + &man.pam.close.session.3; performs tasks + associated with session tear-down: add an entry in + the utmp and wtmp databases, stop the SSH agent, etc. @@ -474,10 +479,10 @@ sshd password required pam_permit.so - pam_chauthtok changes the - authentication token, optionally verifying that it - is sufficiently hard to guess, has not been used - previously, etc. + &man.pam.chauthtok.3; changes the authentication + token, optionally verifying that it is sufficiently + hard to guess, has not been used previously, + etc. @@ -486,8 +491,8 @@ sshd password required pam_permit.so
-
- Modules +
+ Modules Modules are a very central concept in PAM; after all, they are the M in PAM. A PAM @@ -497,14 +502,44 @@ sshd password required pam_permit.so 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 (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.) +
+ Module Naming + + FreeBSD implements each mechanism in a single module, + named + pam_mechanism.so + (for instance, pam_unix.so for the Unix + mechanism.) Other implementations sometimes have separate + modules for separate facilities, and include the facility + name as well as the mechanism name in the module name. To + name one example, Solaris has a + pam_dial_auth.so.1 module which is + commonly used to authenticate dialup users. +
+ +
+ Module Versioning + + FreeBSD's original PAM implementation, based on + Linux-PAM, did not use version numbers for PAM modules. + This would commonly cause problems with legacy applications, + which might be linked against older versions of the system + libraries, as there was no way to load a matching version of + the required modules. + + OpenPAM, on the other hand, looks for modules that have + the same version number as the PAM library (currently 2), + and only falls back to an unversioned module if no versioned + module could be loaded. Thus legacy modules can be provided + for legacy applications, while allowing new (or newly built) + applications to take advantage of the most recent + modules. + + Although Solaris PAM modules commonly have a version + number, they're not truly versioned, because the number is a + part of the module name and must be included in the + configuration. +
@@ -513,7 +548,7 @@ sshd password required pam_permit.so 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 + &man.pam.start.3; 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 @@ -586,8 +621,8 @@ sshd password required pam_permit.so in the same chain as different, unrelated modules.
-
- Transactions +
+ Transactions The lifecycle of a typical PAM transaction is described below. Note that if this any of these steps fails, the server @@ -604,53 +639,51 @@ sshd password required pam_permit.so - 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 calls &man.pam.start.3; 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. + using &man.pam.set.item.3;. - The server calls pam_authenticate - to authenticate the applicant. + The server calls &man.pam.authenticate.3; to + authenticate the applicant. - The server calls pam_acct_mgmt to - verify that the requested account is available and valid. - The pam_acct_mgmt function will - return PAM_NEW_AUTHTOK_REQD if the - account's password has expired. + The server calls &man.pam.acct.mgmt.3; 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. 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. + calls &man.pam.chauthtok.3; to force the client to change + the authentication token for the requested account. 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. + authenticated, the server calls &man.pam.setcred.3; 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 calls &man.pam.open.session.3; to set up the + session. @@ -661,15 +694,14 @@ sshd password required pam_permit.so Once the server is done serving the client, it calls - pam_close_session to tear down the - session. + &man.pam.close.session.3; 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. + Finally, the server calls &man.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.
@@ -679,7 +711,8 @@ sshd password required pam_permit.so PAM Configuration
- Location of configuration files + Location of + configuration files The traditional PAM configuration file is /etc/pam.conf. This file contains all @@ -701,20 +734,20 @@ sshd password required pam_permit.so 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 + still does that, but FreeBSD's stock configuration 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-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 - be used as a fall-back for these services. + OpenPAM and Linux-PAM offer 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. This + is the preferred mechanism in FreeBSD 5.x.. 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 @@ -729,25 +762,35 @@ sshd password required pam_permit.so 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. + same file can be used for multiple differently-named + services. One other advantage is that third-party software can easily install policies for their services without the need to - edit /etc/pam.conf. + edit /etc/pam.conf. True to the FreeBSD + tradition, OpenPAM will even look for policy files in + /usr/local/etc/pam.d/ if no configuration + for the requested service is present in + /etc/pam.d/ or + /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. + Finally, whichever configuration mechanism you choose, the + magic policy other is used + as a fall-back for any service that does not have its own + policy.
-
- Breakdown of a configuration line +
+ Breakdown of a + 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 the 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 are @@ -771,19 +814,21 @@ sshd password required pam_permit.so 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. + 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.
-
- Policies +
+ Policies This section has not yet been written.
-
- PAM Modules +
+ FreeBSD PAM Modules This section has not yet been written.
@@ -815,20 +860,28 @@ sshd password required pam_permit.so
- Sample PAM application + Sample PAM Application The following is a minimal implementation of &man.su.1; - using PAM. Note that it uses the Linux-PAM-specific - misc_conv conversation function, which is + using PAM. Note that it uses the OpenPAM-specific + &man.openpam.ttyconv.3; conversation function, which is prototyped in security/pam_misc.h. + class="headerfile">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 the appendix is a good + starting point, but should not be used in real-world + applications. - Sample PAM module + Sample PAM Module The following is a minimal implementation of &man.pam.unix.8;, offering only authentication services. It @@ -841,6 +894,23 @@ sshd password required pam_permit.so format="linespecific"> + + Sample PAM Conversation + Function + + The conversation function presented below is a greatly + 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're 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 + convesation function can reasonably get. + + + + Further Reading