diff options
| author | Andrew G. Morgan <morgan@kernel.org> | 2000-06-20 22:10:38 +0000 |
|---|---|---|
| committer | Andrew G. Morgan <morgan@kernel.org> | 2000-06-20 22:10:38 +0000 |
| commit | ea488580c42e8918445a945484de3c8a5addc761 (patch) | |
| tree | c992f3ba699caafedfadc16af38e6359c3c24698 /doc/modules | |
| download | pam-ea488580c42e8918445a945484de3c8a5addc761.tar.gz pam-ea488580c42e8918445a945484de3c8a5addc761.tar.bz2 pam-ea488580c42e8918445a945484de3c8a5addc761.zip | |
Initial revision
Diffstat (limited to 'doc/modules')
30 files changed, 3896 insertions, 0 deletions
diff --git a/doc/modules/README b/doc/modules/README new file mode 100644 index 00000000..df091939 --- /dev/null +++ b/doc/modules/README @@ -0,0 +1,13 @@ +$Id$ + +This directory contains a number of sgml sub-files. One for each +documented module. They contain a description of each module and give +some indication of its reliability. + +Additionally, there is a 'module.sgml-template' file which should be +used as a blank form for new module descriptions. + +Please feel free to submit amendments/comments etc. regarding these +files to: + + Andrew G. Morgan <morgan@parc.power.net> diff --git a/doc/modules/module.sgml-template b/doc/modules/module.sgml-template new file mode 100644 index 00000000..d0b0e3c6 --- /dev/null +++ b/doc/modules/module.sgml-template @@ -0,0 +1,170 @@ +<!-- + + $Id$ + + This template file was written by Andrew G. Morgan + <morgan@parc.power.net> + +[ + Text that should be deleted/replaced, is enclosed within + '[' .. ']' + marks. For example, this text should be deleted! +] + +--> + +<sect1> [*Familiar full name of module*, eg. The "allow all" module.] + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +[ + insert the name of the module + + Blank is not permitted. +] + +<tag><bf>Author[s]:</bf></tag> + +[ + Insert author names here + + Blank is not permitted. If in doubt, put "unknown" if the + author wishes to remain anonymous, put "anonymous". +] + +<tag><bf>Maintainer:</bf></tag> + +[ + Insert names and date-begun of most recent maintainer. +] + +<tag><bf>Management groups provided:</bf></tag> + +[ + list the subset of four management groups supported by the + module. Choose from: account; authentication; password; + session. + + Blank entries are not permitted. Explicitly list all of the + management groups. In the future more may be added to libpam! +] + +<tag><bf>Cryptographically sensitive:</bf></tag> + +[ + Indicate whether this module contains code that can perform + reversible (strong) encryption. This field is primarily to + ensure that people redistributing it are not unwittingly + breaking laws... + + Modules may also require the presence of some local library + that performs the necessary encryption via some standard API. + In this case "uses API" can be included in this field. The + library in question should be added to the system requirements + below. + + Blank = no cryptography is used by module. +] + +<tag><bf>Security rating:</bf></tag> + +[ + Initially, this field should be left blank. If someone takes + it upon themselves to test the strength of the module, it can + later be filled. + + Blank = unknown. +] + +<tag><bf>Clean code base:</bf></tag> + +[ + This will probably be filled by the libpam maintainer. + It can be considered to be a public humiliation list. :*) + + I am of the opinion that "gcc -with_all_those_flags" is + trying to tell us something about whether the program + works as intended. Since there is currently no Security + evaluation procedure for modules IMHO this is not a + completely unreasonable indication (a lower bound anyway) + of the reliability of a module. + + This field would indicate the number and flavor of + warnings that gcc barfs up when trying to compile the + module as part of the tree. Is this too tyrannical? + + Blank = Linux-PAM maintainer has not tested it :) +] + +<tag><bf>System dependencies:</bf></tag> + +[ + here we list config files, dynamic libraries needed, system + resources, kernel options.. etc. + + Blank = nothing more than libc required. +] + +<tag><bf>Network aware:</bf></tag> + +[ + Does the module base its behavior on probing a network + connection? Does it expect to be protected by the + application? + + Blank = Ignorance of network. +] + +</descrip> + +<sect2>Overview of module + +[ + some text describing the intended actions of the module + general comments mainly (specifics in sections + below). +] + +[ + + [ now we have a <sect2> level subsection for each of the + management groups. Include as many as there are groups + listed above in the synopsis ] + +<sect2>[ Account | Authentication | Password | Session ] component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> + +[ + List the supported arguments (leave their description for the + description below. + + Blank = no arguments are read and nothing is logged to syslog + about any arguments that are passed. Note, this + behavior is contrary to the RFC! +] + +<tag><bf>Description:</bf></tag> + +[ + This component of the module performs the task of ... +] + +<tag><bf>Examples/suggested usage:</bf></tag> + +[ + Here we list some doos and don'ts for this module. +] + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/modules/pam_access.sgml b/doc/modules/pam_access.sgml new file mode 100644 index 00000000..e192d12e --- /dev/null +++ b/doc/modules/pam_access.sgml @@ -0,0 +1,93 @@ +<!-- + + pam_access module docs added by Tim Berger <timb@transmeta.com> + +--> + +<sect1> The access module + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> + +<tt>pam_access</tt> + + +<tag><bf>Author[s]:</bf></tag> + +Alexei Nogin <alexei@nogin.dnttm.ru> + +<tag><bf>Maintainer:</bf></tag> + +Author + +<tag><bf>Management groups provided:</bf></tag> + +account + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> + +<tag><bf>System dependencies:</bf></tag> +Requires a configuration file <tt>/etc/security/access.conf</tt> +<tag><bf>Network aware:</bf></tag> + +Through <tt/PAM_TTY/ if set, otherwise attempts getting tty name of +the stdin file descriptor with <tt/ttyname()/. Standard +gethostname(), <tt/yp_get_default_domain()/, <tt/gethostbyname()/ +calls. <bf/NIS/ is used for netgroup support. + +</descrip> + +<sect2>Overview of module + +<p> +Provides logdaemon style login access control. + +<sect2> Account component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> + +<tag><bf>Description:</bf></tag> + +This module provides logdaemon style login access control based on +login names and on host (or domain) names, internet addresses (or +network numbers), or on terminal line names in case of non-networked +logins. Diagnostics are reported through <tt/syslog(3)/. Wietse +Venema's <tt/login_access.c/ from <em/logdaemon-5.6/ is used with +several changes by A. Nogin. + +<tag><bf>Examples/suggested usage:</bf></tag> + +Use of module is recommended, for example, on administrative machines +such as <bf/NIS/ servers and mail servers where you need several accounts +active but don't want them all to have login capability. + +For <tt>/etc/pam.d</tt> style configurations where your modules live +in <tt>/lib/security</tt>, start by adding the following line to +<tt>/etc/pam.d/login</tt>, <tt>/etc/pam.d/rlogin</tt>, +<tt>/etc/pam.d/rsh</tt> and <tt>/etc/pam.d/ftp</tt>: + +<tscreen> +<verb> +account required /lib/security/pam_access.so +</verb> +</tscreen> + +Note that use of this module is not effective unless your system ignores +<tt>.rhosts</tt> files. See the the pam_rhosts_auth documentation. + +A sample <tt>access.conf</tt> configuration file is included with the +distribution. + +</descrip> + diff --git a/doc/modules/pam_chroot.sgml b/doc/modules/pam_chroot.sgml new file mode 100644 index 00000000..ec739c18 --- /dev/null +++ b/doc/modules/pam_chroot.sgml @@ -0,0 +1,86 @@ +<!-- + $Id$ + + This file was written by Bruce Campbell <brucec@humbug.org.au> +--> + +<sect1>Chroot + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +<tt/pam_chroot/ + +<tag><bf>Author:</bf></tag> +Bruce Campbell <brucec@humbug.org.au> + +<tag><bf>Maintainer:</bf></tag> +Author; proposed on 20/11/96 - email for status + +<tag><bf>Management groups provided:</bf></tag> +account; session; authentication + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> +Unwritten. + +<tag><bf>System dependencies:</bf></tag> + +<tag><bf>Network aware:</bf></tag> +Expects localhost. + +</descrip> + +<sect2>Overview of module + +<p> +This module is intended to provide a transparent wrapper around the +average user, one that puts them in a fake file-system (eg, their +'<tt>/</tt>' is really <tt>/some/where/else</tt>). + +<p> +Useful if you have several classes of users, and are slightly paranoid +about security. Can be used to limit who else users can see on the +system, and to limit the selection of programs they can run. + +<sect2>Account component: + +<p> +<em/Need more info here./ + +<sect2>Authentication component: + +<p> +<em/Need more info here./ + +<sect2>Session component: + +<p> +<em/Need more info here./ + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +Arguments and logging levels for the PAM version are being worked on. + +<tag><bf>Description:</bf></tag> + +<tag><bf>Examples/suggested usage:</bf></tag> +Do provide a reasonable list of programs - just tossing 'cat', 'ls', 'rm', +'cp' and 'ed' in there is a bit... +<p> +Don't take it to extremes (eg, you can set up a separate environment for +each user, but its a big waste of your disk space.) + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/modules/pam_cracklib.sgml b/doc/modules/pam_cracklib.sgml new file mode 100644 index 00000000..f5b2359a --- /dev/null +++ b/doc/modules/pam_cracklib.sgml @@ -0,0 +1,259 @@ +<!-- + $Id$ + + This file was written by Andrew G. Morgan <morgan@parc.power.net> + long password amendments are from Philip W. Dalrymple III <pwd@mdtsoft.com> +--> + +<sect1>Cracklib pluggable password strength-checker + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> + +pam_cracklib + +<tag><bf>Author:</bf></tag> + +Cristian Gafton <gafton@redhat.com> + +<tag><bf>Maintainer:</bf></tag> + +Author. + +<tag><bf>Management groups provided:</bf></tag> + +password + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> + +<tag><bf>System dependencies:</bf></tag> + +Requires the system library <tt/libcrack/ and a system dictionary: +<tt>/usr/lib/cracklib_dict</tt>. + +<tag><bf>Network aware:</bf></tag> + +</descrip> + +<sect2>Overview of module + +<p> +This module can be plugged into the <tt/password/ stack of a given +application to provide some plug-in strength-checking for passwords. +(XXX - note this does not necessarily work with the pam_unix module, +although it is known to work with the pam_pwdb replacement for the +unix module -- see example and pam_pwdb write up for more +information). + +<p> +This module works in the following manner: it first calls the +<em>Cracklib</em> routine to check the strength of the password; if +crack likes the password, the module does an additional set of +strength checks. These checks are: +<itemize> + +<item> <bf/Palindrome/ - + +Is the new password a palindrome of the old one? + +<item> <bf/Case Change Only/ - + +Is the new password the the old one with only a change of case? + +<item> <bf/Similar/ - + +Is the new password too much like the old one? This is controlled +by one argument, <tt/difok/ which is a number of characters that if +different between the old and new are enough to accept the new +password, this defaults to 10 or 1/2 the size of the new password +whichever is smaller. + +<item> <bf/Simple/ - + +Is the new password too small? This is controlled by 5 arguments +<tt/minlen/, <tt/dcredit/, <tt/ucredit/, <tt/lcredit/, and +<tt/ocredit/. See the section on the arguments for the details of how +these work and there defaults. + +<item> <bf/Rotated/ - + +Is the new password a rotated version of the old password? + +<item> <bf/Already used/ - + +Was the password used in the past? Previously used passwords are to +be found in /etc/security/opasswd. + +</itemize> + +<p> +This module with no arguments will work well for standard unix +password encryption. With md5 encryption, passwords can be longer +than 8 characters and the default settings for this module can make it +hard for the user to choose a satisfactory new password. Notably, the +requirement that the new password contain no more than 1/2 of the +characters in the old password becomes a non-trivial constraint. For +example, an old password of the form "the quick brown fox jumped over +the lazy dogs" would be difficult to change... In addition, the +default action is to allow passwords as small as 5 characters in +length. For a md5 systems it can be a good idea to increase the +required minimum size of a password. One can then allow more credit +for different kinds of characters but accept that the new password may +share most of these characters with the old password. + +<sect2>Password component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> + +<tt/debug/; <tt/type=XXX/; <tt/retry=N/; <tt/difok=N/; <tt/minlen=N/; +<tt/dcredit=N/; <tt/ucredit=N/; <tt/lcredit=N/; <tt/ocredit=N/; + +<tag><bf>Description:</bf></tag> + +The action of this module is to prompt the user for a password and +check its strength against a system dictionary and a set of rules for +identifying poor choices. + +<p> +The default action is to prompt for a single password, check its +strength and then, if it is considered strong, prompt for the password +a second time (to verify that it was typed correctly on the first +occasion). All being well, the password is passed on to subsequent +modules to be installed as the new authentication token. + +<p> +The default action may be modified in a number of ways using the +arguments recognized by the module: +<itemize> + +<item> <tt/debug/ - + +this option makes the module write information to syslog(3) indicating +the behavior of the module (this option does <bf/not/ write password +information to the log file). + +<item> <tt/type=XXX/ - + +the default action is for the module to use the following prompts when +requesting passwords: ``New UNIX password: '' and ``Retype UNIX +password: ''. Using this option you can replace the word UNIX with +<tt/XXX/. + +<item> <tt/retry=N/ - + +the default number of times this module will request a new password +(for strength-checking) from the user is 1. Using this argument this +can be increased to <tt/N/. + +<item> <tt/difok=N/ - + +This argument will change the default of 10 for the number of +characters in the new password that must not be present in the old +password. In addition, if 1/2 of the characters in the new password +are different then the new password will be accepted anyway. + +<item> <tt/minlen=N/ - + +The minimum acceptable size for the new password plus one. In +addition to the number of characters in the new password, credit (of ++1 in length) is given for each different kind of character (<em>other, +upper, lower</em> and <em/digit/). The default for this parameter is +9 which is good for a old style UNIX password all of the same type of +character but may be too low to exploit the added security of a md5 +system. Note that there is a pair of length limits in +<em>Cracklib</em> itself, a "way too short" limit of 4 which is hard +coded in and a defined limit (6) that will be checked without +reference to <tt>minlen</tt>. If you want to allow passwords as short +as 5 characters you should either not use this module or recompile +the crack library and then recompile this module. + +<item> <tt/dcredit=N/ - + +This is the maximum credit for having digits in the new password. If +you have less than or <tt/N/ digits, each digit will count +1 towards +meeting the current <tt/minlen/ value. The default for <tt/dcredit/ +is 1 which is the recommended value for <tt/minlen/ less than 10. + +<item> <tt/ucredit=N/ - + +This is the maximum credit for having upper case letters in the new +password. If you have less than or <tt/N/ upper case letters each +letter will count +1 towards meeting the current <tt/minlen/ value. +The default for <tt/ucredit/ is 1 which is the recommended value for +<tt/minlen/ less than 10. + +<item> <tt/lcredit=N/ - + +This is the maximum credit for having lower case letters in the new +password. If you have less than or <tt/N/ lower case letters, each +letter will count +1 towards meeting the current <tt/minlen/ value. +The default for <tt/lcredit/ is 1 which is the recommended value for +<tt/minlen/ less than 10. + +<item> <tt/ocredit=N/ - + +This is the maximum credit for having other characters in the new +password. If you have less than or <tt/N/ other characters, each +character will count +1 towards meeting the current <tt/minlen/ value. +The default for <tt/ocredit/ is 1 which is the recommended value for +<tt/minlen/ less than 10. + +</itemize> + +<tag><bf>Examples/suggested usage:</bf></tag> + +(At the time of writing, this module can only be stacked before the +<tt/pam_pwdb/ module. Cracklib strength checking may be compiled by +default into the <tt/pam_unix/ module.) + +<p> +For an example of the use of this module, we show how it may be +stacked with the password component of <tt/pam_pwdb/: +<tscreen> +<verb> +# +# These lines stack two password type modules. In this example the +# user is given 3 opportunities to enter a strong password. The +# "use_authtok" argument ensures that the pam_pwdb module does not +# prompt for a password, but instead uses the one provided by +# pam_cracklib. +# +passwd password required pam_cracklib.so retry=3 +passwd password required pam_pwdb.so use_authtok +</verb> +</tscreen> + +<p> +Another example (in the <tt>/etc/pam.d/passwd</tt> format) is for the +case that you want to use md5 password encryption: +<tscreen> +<verb> +#%PAM-1.0 +# +# These lines allow a md5 systems to support passwords of at least 14 +# bytes with extra credit of 2 for digits and 2 for others the new +# password must have at least three bytes that are not present in the +# old password +# +password required pam_cracklib.so \ + difok=3 minlen=15 dcredit= 2 ocredit=2 +password required pam_pwdb.so use_authtok nullok md5 +</verb> +</tscreen> + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/modules/pam_deny.sgml b/doc/modules/pam_deny.sgml new file mode 100644 index 00000000..6e1f2992 --- /dev/null +++ b/doc/modules/pam_deny.sgml @@ -0,0 +1,179 @@ +<!-- + $Id$ + + This file was written by Andrew G. Morgan <morgan@parc.power.net> +--> + +<sect1>The locking-out module + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +pam_deny + +<tag><bf>Author:</bf></tag> +Andrew G. Morgan <morgan@parc.power.net> + +<tag><bf>Maintainer:</bf></tag> +current <bf/Linux-PAM/ maintainer + +<tag><bf>Management groups provided:</bf></tag> +account; authentication; password; session + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> +clean. + +<tag><bf>System dependencies:</bf></tag> + +<tag><bf>Network aware:</bf></tag> + +</descrip> + +<sect2>Overview of module + +<p> +This module can be used to deny access. It always indicates a failure +to the application through the PAM framework. As is commented in the +overview section <ref id="overview-section" name="above">, this module +might be suitable for using for default (the <tt/OTHER/) entries. + +<sect2>Account component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> + +<tag><bf>Description:</bf></tag> + +This component does nothing other than return a failure. The +failure type is <tt/PAM_ACCT_EXPIRED/. + +<tag><bf>Examples/suggested usage:</bf></tag> + +Stacking this module with type <tt/account/ will prevent the user from +gaining access to the system via applications that refer to +<bf/Linux-PAM/'s account management function <tt/pam_acct_mgmt()/. + +<p> +The following example would make it impossible to login: +<tscreen> +<verb> +# +# add this line to your other login entries to disable all accounts +# +login account required pam_deny.so +</verb> +</tscreen> + +</descrip> + +<sect2>Authentication component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> + +<tag><bf>Description:</bf></tag> + +This component does nothing other than return a failure. The failure +type is <tt/PAM_AUTH_ERR/ in the case that <tt/pam_authenticate()/ is +called (when the application tries to authenticate the user), and is +<tt/PAM_CRED_UNAVAIL/ when the application calls <tt/pam_setcred()/ +(to establish and set the credentials of the user -- it is unlikely +that this function will ever be called in practice). + +<tag><bf>Examples/suggested usage:</bf></tag> + +To deny access to default applications with this component of the +<tt/pam_deny/ module, you might include the following line in your +<bf/Linux-PAM/ configuration file: +<tscreen> +<verb> +# +# add this line to your existing OTHER entries to prevent +# authentication succeeding with default applications. +# +OTHER auth required pam_deny.so +</verb> +</tscreen> + +</descrip> + +<sect2>Password component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> + +<tag><bf>Description:</bf></tag> + +This component of the module denies the user the opportunity to change +their password. It always responds with <tt/PAM_AUTHTOK_ERR/ when +invoked. + +<tag><bf>Examples/suggested usage:</bf></tag> + +This module should be used to prevent an application from updating the +applicant user's password. For example, to prevent <tt/login/ from +automatically prompting for a new password when the old one has +expired you should include the following line in your configuration +file: +<tscreen> +<verb> +# +# add this line to your other login entries to prevent the login +# application from being able to change the user's password. +# +login password required pam_deny.so +</verb> +</tscreen> + +</descrip> + +<sect2>Session component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> + +<tag><bf>Description:</bf></tag> + +This aspect of the module prevents an application from starting a +session on the host computer. + +<tag><bf>Examples/suggested usage:</bf></tag> + +Together with another session module, that displays a message of the +day perhaps (XXX - such a module needs to be written), +this module can be used to block a user from starting a shell. Given +the presence of a <tt/pam_motd/ module, we might use the following +entries in the configuration file to inform the user it is system +time: +<tscreen> +<verb> +# +# An example to see how to configure login to refuse the user a +# session (politely) +# +login session required pam_motd.so \ + file=/etc/system_time +login session required pam_deny.so +</verb> +</tscreen> + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/modules/pam_env.sgml b/doc/modules/pam_env.sgml new file mode 100644 index 00000000..8057b38d --- /dev/null +++ b/doc/modules/pam_env.sgml @@ -0,0 +1,141 @@ +<!-- + $Id$ + + This file was written by Dave Kinchlea <kinch@kinch.ark.com> + Ed. AGM +--> + +<sect1>Set/unset environment variables + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +<tt/pam_env/ + +<tag><bf>Author:</bf></tag> +Dave Kinchlea <kinch@kinch.ark.com> + +<tag><bf>Maintainer:</bf></tag> +Author + +<tag><bf>Management groups provided:</bf></tag> +Authentication (setcred) + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> + +<tag><bf>System dependencies:</bf></tag> +<tt>/etc/security/pam_env.conf</tt> + +<tag><bf>Network aware:</bf></tag> + +</descrip> + +<sect2>Overview of module + +<p> +This module allows the (un)setting of environment variables. Supported +is the use of previously set environment variables as well as +<em>PAM_ITEM</em>s such as <tt>PAM_RHOST</tt>. + +<sect2>Authentication component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +<tt/debug/; <tt/conffile=/<em/configuration-file-name/; +<tt/envfile/=/<em/env-file-name/; <tt/readenv/=/<em/0|1/ + +<tag><bf>Description:</bf></tag> +This module allows you to (un)set arbitrary environment variables +using fixed strings, the value of previously set environment variables +and/or <em/PAM_ITEM/s. + +<p> +All is controlled via a configuration file (by default, +<tt>/etc/security/pam_env.conf</tt> but can be overriden with +<tt>connfile</tt> argument). Each line starts with the variable name, +there are then two possible options for each variable <bf>DEFAULT</bf> +and <bf>OVERRIDE</bf>. <bf>DEFAULT</bf> allows and administrator to +set the value of the variable to some default value, if none is +supplied then the empty string is assumed. The <bf>OVERRIDE</bf> +option tells pam_env that it should enter in its value (overriding the +default value) if there is one to use. <bf>OVERRIDE</bf> is not used, +<tt>""</tt> is assumed and no override will be done. + +<p> +<tscreen> +<verb> +VARIABLE [DEFAULT=[value]] [OVERRIDE=[value]] +</verb> +</tscreen> + +<p> +(Possibly non-existent) environment variables may be used in values +using the <tt>${string}</tt> syntax and (possibly +non-existent) <em/PAM_ITEM/s may be used in values using the +<tt>@{string}</tt> syntax. Both the <tt>$</tt> +and <tt>@</tt> characters can be backslash-escaped to be used +as literal values (as in <tt>\$</tt>. Double quotes may +be used in values (but not environment variable names) when white +space is needed <bf>the full value must be delimited by the quotes and +embedded or escaped quotes are not supported</bf>. + +<p> +This module can also parse a file with simple KEY=VAL pairs on seperate +lines (/etc/environment by default). You can change the default file to +parse, with the <em/envfile/ flag and turn it on or off by setting the +<em/readenv/ flag to 1 or 0 respectively. + +<p> +The behavior of this module can be modified with one of the following +flags: + +<p> +<itemize> + +<item><tt/debug/ +- write more information to <tt/syslog(3)/. + +<item><tt/conffile=/<em/filename/ +- by default the file <tt>/etc/security/pam_env.conf</tt> is used as +the configuration file. This option overrides the default. You must +supply a complete path + file name. + +<item><tt/envfile=/<em/filename/ +- by default the file <tt>/etc/environment</tt> is used to load KEY=VAL +pairs directly into the env. This option overrides the default. You must +supply a complete path + file name. + +<item><tt/readenv=/<em/0|1/ +- turns on or off the reading of the file specified by envfile (0 is off, +1 is on). By default this option is on. + +</itemize> + +<tag><bf>Examples/suggested usage:</bf></tag> + +See sample <tt>pam_env.conf</tt> for more information and examples. + +</descrip> + +<!-- +End of sgml insert for this module. +--> + + + + + + + + + + diff --git a/doc/modules/pam_filter.sgml b/doc/modules/pam_filter.sgml new file mode 100644 index 00000000..598279b8 --- /dev/null +++ b/doc/modules/pam_filter.sgml @@ -0,0 +1,150 @@ +<!-- + $Id$ + + This file was written by Andrew G. Morgan <morgan@parc.power.net> +--> + +<sect1>The filter module + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> + +pam_filter + +<tag><bf>Author:</bf></tag> + +Andrew G. Morgan <morgan@parc.power.net> + +<tag><bf>Maintainer:</bf></tag> + +Author. + +<tag><bf>Management groups provided:</bf></tag> + +account; authentication; password; session + +<tag><bf>Cryptographically sensitive:</bf></tag> + +Not yet. + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> + +This module compiles cleanly on Linux based systems. + +<tag><bf>System dependencies:</bf></tag> + +To function it requires <em/filters/ to be installed on the system. + +<tag><bf>Network aware:</bf></tag> + +</descrip> + +<sect2>Overview of module + +<p> +This module was written to offer a plug-in alternative to programs +like ttysnoop (XXX - need a reference). Since writing a filter that +performs this function has not occurred, it is currently only a toy. +The single filter provided with the module simply transposes upper and +lower case letters in the input and output streams. (This can be very +annoying and is not kind to termcap based editors). + +<sect2>Account+Authentication+Password+Session components + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> + +<tt/debug/; <tt/new_term/; <tt/non_term/; <tt/runX/ + +<tag><bf>Description:</bf></tag> + +Each component of the module has the potential to invoke the desired +filter. The filter is always <tt/execv(2)/d with the privilege of the +calling application and <bf/not/ that of the user. For this reason it +cannot usually be killed by the user without closing their session. + +<p> +The behavior of the module can be significantly altered by the +arguments passed to it in the <bf/Linux-PAM/ configuration file: +<itemize> +<item><tt/debug/ - + +this option increases the amount of information logged to +<tt/syslog(3)/ as the module is executed. + +<item><tt/new_term/ - + +the default action of the filter is to set the <tt/PAM_TTY/ item to +indicate the terminal that the user is using to connect to the +application. This argument indicates that the filter should set +<tt/PAM_TTY/ to the filtered pseudo-terminal. + +<item><tt/non_term/ - +don't try to set the <tt/PAM_TTY/ item. + +<item><tt/runX/ - + +in order that the module can invoke a filter it should know when to +invoke it. This argument is required to tell the filter when to do +this. The arguments that follow this one are respectively the full +pathname of the filter to be run and any command line arguments that +the filter might expect. + +<p> +Permitted values for <tt/X/ are <tt/1/ and <tt/2/. These indicate the +precise time the that filter is to be run. To explain this concept it +will be useful to have read the Linux-PAM Module developer's +guide. Basically, for each management group there are up to two ways +of calling the module's functions. + +In the case of the <em/authentication/ and <em/session/ components +there are actually two separate functions. For the case of +authentication, these functions are <tt/_authenticate/ and +<tt/_setcred/ -- here <tt/run1/ means run the filter from the +<tt/_authenticate/ function and <tt/run2/ means run the filter from +<tt/_setcred/. In the case of the session modules, <tt/run1/ implies +that the filter is invoked at the <tt/_open_session/ stage, and +<tt/run2/ for <tt/_close_session/. + +<p> +For the case of the account component. Either <tt/run1/ or <tt/run2/ +may be used. + +<p> +For the case of the password component, <tt/run1/ is used to indicate +that the filter is run on the first occasion <tt/_chauthtok/ is run +(the <tt/PAM_PRELIM_CHECK/ phase) and <tt/run2/ is used to indicate +that the filter is run on the second occasion (the +<tt/PAM_UPDATE_AUTHTOK/ phase). + +</itemize> + +<tag><bf>Examples/suggested usage:</bf></tag> + +At the time of writing there is little real use to be made of this +module. For fun you might try adding the following line to your +login's configuration entries +<tscreen> +<verb> +# +# An example to see how to configure login to transpose upper and +# lower case letters once the user has logged in(!) +# +login session required pam_filter.so \ + run1 /usr/sbin/pam_filter/upperLOWER +</verb> +</tscreen> + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/modules/pam_ftp.sgml b/doc/modules/pam_ftp.sgml new file mode 100644 index 00000000..3c26a5f0 --- /dev/null +++ b/doc/modules/pam_ftp.sgml @@ -0,0 +1,93 @@ +<!-- + $Id$ + + This file was written by Andrew G. Morgan <morgan@linux.kernel.org> +--> + +<sect1>Anonymous access module + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +<tt/pam_ftp.so/ + +<tag><bf>Author:</bf></tag> +Andrew G. Morgan <morgan@linux.kernel.org> + +<tag><bf>Maintainer:</bf></tag> +Author. + +<tag><bf>Management groups provided:</bf></tag> +authentication + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> + +<tag><bf>System dependencies:</bf></tag> + +<tag><bf>Network aware:</bf></tag> +prompts for email address of user; easily spoofed (XXX - needs work) + +</descrip> + +<sect2>Overview of module + +<p> +The purpose of this module is to provide a pluggable anonymous ftp +mode of access. + +<sect2>Authentication component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +<tt/debug/; +<tt/users=XXX,YYY,.../; +<tt/ignore/ + +<tag><bf>Description:</bf></tag> + +This module intercepts the user's name and password. If the name is +``<tt/ftp/'' or ``<tt/anonymous/'', the user's password is broken up +at the `<tt/@/' delimiter into a <tt/PAM_RUSER/ and a <tt/PAM_RHOST/ +part; these pam-items being set accordingly. The username is set to +``<tt/ftp/''. In this case the module succeeds. Alternatively, the +module sets the <tt/PAM_AUTHTOK/ item with the entered password and +fails. + +<p> +The behavior of the module can be modified with the following flags: +<itemize> +<item><tt/debug/ - +log more information to with <tt/syslog(3)/. + +<item><tt/users=XXX,YYY,.../ - +instead of ``<tt/ftp/'' or ``<tt/anonymous/'', provide anonymous login +to the comma separated list of users; ``<tt/XXX,YYY,.../''. Should the +applicant enter one of these usernames the returned username is set to +the first in the list; ``<tt/XXX/''. + +<item><tt/ignore/ - +pay no attention to the email address of the user (if supplied). + +</itemize> + +<tag><bf>Examples/suggested usage:</bf></tag> + +An example of the use of this module is provided in the configuration +file section <ref id="configuration" name="above">. With care, this +module could be used to provide new/temporary account anonymous +login. + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/modules/pam_group.sgml b/doc/modules/pam_group.sgml new file mode 100644 index 00000000..8251e3dd --- /dev/null +++ b/doc/modules/pam_group.sgml @@ -0,0 +1,108 @@ +<!-- + $Id$ + + This file was written by Andrew G. Morgan <morgan@parc.power.net> +--> + +<sect1>The group access module + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +<tt/pam_group/ + +<tag><bf>Author:</bf></tag> +Andrew G. Morgan <morgan@parc.power.net> + +<tag><bf>Maintainer:</bf></tag> +Author. + +<tag><bf>Management groups provided:</bf></tag> +authentication + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> +Sensitive to <em/setgid/ status of file-systems accessible to users. + +<tag><bf>Clean code base:</bf></tag> + +<tag><bf>System dependencies:</bf></tag> +Requires an <tt>/etc/security/group.conf</tt> file. Can be compiled +with or without <tt/libpwdb/. + +<tag><bf>Network aware:</bf></tag> +Only through correctly set <tt/PAM_TTY/ item. + +</descrip> + +<sect2>Overview of module + +<p> +This module provides group-settings based on the user's name and the +terminal they are requesting a given service from. It takes note of +the time of day. + +<sect2>Authentication component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> + +<tag><bf>Description:</bf></tag> + +This module does not authenticate the user, but instead it grants +group memberships (in the credential setting phase of the +authentication module) to the user. Such memberships are based on the +service they are applying for. The group memberships are listed in +text form in the <tt>/etc/security/group.conf</tt> file. + +<tag><bf>Examples/suggested usage:</bf></tag> + +For this module to function correctly there must be a correctly +formatted <tt>/etc/security/groups.conf</tt> file present. The format +of this file is as follows. Group memberships are given based on the +service application satisfying any combination of lines in the +configuration file. Each line (barring comments which are preceded by +`<tt/#/' marks) has the following +syntax: +<tscreen> +<verb> +services ; ttys ; users ; times ; groups +</verb> +</tscreen> +Here the first four fields share the syntax of the <tt>pam_time</tt> +configuration file; <tt>/etc/security/pam_time.conf</tt>, and the last +field, the <tt/groups/ field, is a comma (or space) separated list of +the text-names of a selection of groups. If the users application for +service satisfies the first four fields, the user is granted membership +of the listed groups. + +<p> +As stated in above this module's usefulness relies on the file-systems +accessible to the user. The point being that once granted the +membership of a group, the user may attempt to create a <em/setgid/ +binary with a restricted group ownership. Later, when the user is not +given membership to this group, they can recover group membership with +the precompiled binary. The reason that the file-systems that the user +has access to are so significant, is the fact that when a system is +mounted <em/nosuid/ the user is unable to create or execute such a +binary file. For this module to provide any level of security, all +file-systems that the user has write access to should be mounted +<em/nosuid/. + +<p> +The <tt>pam_group</tt> module fuctions in parallel with the +<tt>/etc/group</tt> file. If the user is granted any groups based on +the behavior of this module, they are granted <em>in addition</em> to +those entries <tt>/etc/group</tt> (or equivalent). + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/modules/pam_issue.sgml b/doc/modules/pam_issue.sgml new file mode 100644 index 00000000..1f617e3b --- /dev/null +++ b/doc/modules/pam_issue.sgml @@ -0,0 +1,120 @@ +<!-- + +Ben Collins <bcollins@debian.org> + +--> + +<sect1>Add issue file to user prompt + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +<tt/pam_issue/ + +<tag><bf>Author:</bf></tag> +Ben Collins <bcollins@debian.org> + +<tag><bf>Maintainer:</bf></tag> +Author + +<tag><bf>Management groups provided:</bf></tag> +Authentication (pam_sm_authenticate) + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> + +<tag><bf>System dependencies:</bf></tag> + +<tag><bf>Network aware:</bf></tag> + +</descrip> + +<sect2>Overview of module + +<p> +This module prepends the issue file (<em>/etc/issue</em> by default) when +prompting for a username. + +<sect2>Authentication component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +<tt/issue=issue-file-name/; <tt/noesc/; + +<tag><bf>Description:</bf></tag> +This module allows you to prepend an issue file to the username prompt. It +also by default parses escape codes in the issue file similar to some +common getty's (using \x format). +<p> +Recognized escapes: +<itemize> + +<item><tt/d/ +- current date + +<item><tt/s/ +- operating system name + +<item><tt/l/ +- name of this tty + +<item><tt/m/ +- architecture of this system (i686, sparc, powerpc, ...) + +<item><tt/n/ +- hostname of this system + +<item><tt/o/ +- domainname of this system + +<item><tt/r/ +- release number of the operation system (eg. 2.2.12) + +<item><tt/t/ +- current time + +<item><tt/u/ +- number of users currently logged in + +<item><tt/U/ +- same as <tt/u/, except it is suffixed with "user" or "users" (eg. "1 +user" or "10 users" + +<item><tt/v/ +- version/build-date of the operating system (eg. "#3 Mon Aug 23 14:38:16 +EDT 1999" on Linux). + +</itemize> + +<p> +The behavior of this module can be modified with one of the following +flags: + +<p> +<itemize> + +<item><tt/issue/ +- the file to output if not using the default + +<item><tt/noesc/ +- turns off escape code parsing + +</itemize> + +<tag><bf>Examples/suggested usage:</bf></tag> + +login auth pam_issue.so issue=/etc/issue + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/modules/pam_krb4.sgml b/doc/modules/pam_krb4.sgml new file mode 100644 index 00000000..16ce8183 --- /dev/null +++ b/doc/modules/pam_krb4.sgml @@ -0,0 +1,126 @@ +<!-- + $Id$ + + This file was written by Derrick J. Brashear <shadow@DEMENTIA.ORG> +--> + +<sect1>The Kerberos 4 module. + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +<tt/pam_krb4/ + +<tag><bf>Author:</bf></tag> +Derrick J. Brashear <shadow@dementia.org> + +<tag><bf>Maintainer:</bf></tag> +Author. + +<tag><bf>Management groups provided:</bf></tag> +authentication; password; session + +<tag><bf>Cryptographically sensitive:</bf></tag> +uses API + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> + +<tag><bf>System dependencies:</bf></tag> +libraries - <tt/libkrb/, <tt/libdes/, <tt/libcom_err/, <tt/libkadm/; +and a set of Kerberos include files. + +<tag><bf>Network aware:</bf></tag> +Gets Kerberos ticket granting ticket via a Kerberos key distribution +center reached via the network. + +</descrip> + +<sect2>Overview of module + +<p> +This module provides an interface for doing Kerberos verification of a +user's password, getting the user a Kerberos ticket granting ticket +for use with the Kerberos ticket granting service, destroying the +user's tickets at logout time, and changing a Kerberos password. + +<sect2> Session component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> + +<tag><bf>Description:</bf></tag> + +This component of the module currently sets the user's <tt/KRBTKFILE/ +environment variable (although there is currently no way to export +this), as well as deleting the user's ticket file upon logout (until +<tt/PAM_CRED_DELETE/ is supported by <em/login/). + +<tag><bf>Examples/suggested usage:</bf></tag> + +This part of the module won't be terribly useful until we can change +the environment from within a <tt/Linux-PAM/ module. + +</descrip> + +<sect2> Password component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +<tt/use_first_pass/; <tt/try_first_pass/ + +<tag><bf>Description:</bf></tag> + +This component of the module changes a user's Kerberos password +by first getting and using the user's old password to get +a session key for the password changing service, then sending +a new password to that service. + +<tag><bf>Examples/suggested usage:</bf></tag> + +This should only be used with a real Kerberos v4 <tt/kadmind/. It +cannot be used with an AFS kaserver unless special provisions are +made. Contact the module author for more information. + +</descrip> + +<sect2> Authentication component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +<tt/use_first_pass/; <tt/try_first_pass/ + +<tag><bf>Description:</bf></tag> + +This component of the module verifies a user's Kerberos password +by requesting a ticket granting ticket from the Kerberos server +and optionally using it to attempt to retrieve the local computer's +host key and verifying using the key file on the local machine if +one exists. + +It also writes out a ticket file for the user to use later, and +deletes the ticket file upon logout (not until <tt/PAM_CRED_DELETE/ +is called from <em/login/). + +<tag><bf>Examples/suggested usage:</bf></tag> + +This module can be used with a real Kerberos server using MIT +v4 Kerberos keys. The module or the system Kerberos libraries +may be modified to support AFS style Kerberos keys. Currently +this is not supported to avoid cryptography constraints. + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/modules/pam_lastlog.sgml b/doc/modules/pam_lastlog.sgml new file mode 100644 index 00000000..2ade5baa --- /dev/null +++ b/doc/modules/pam_lastlog.sgml @@ -0,0 +1,119 @@ +<!-- + $Id$ + + This file was written by Andrew G. Morgan <morgan@parc.power.net> +--> + +<sect1>The last login module + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +<tt/pam_lastlog/ + +<tag><bf>Author:</bf></tag> +Andrew G. Morgan <morgan@parc.power.net> + +<tag><bf>Maintainer:</bf></tag> +Author + +<tag><bf>Management groups provided:</bf></tag> +auth + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> + +<tag><bf>System dependencies:</bf></tag> +uses information contained in the <tt>/var/log/lastlog</tt> file. + +<tag><bf>Network aware:</bf></tag> + +</descrip> + +<sect2>Overview of module + +<p> +This session module maintains the <tt>/var/log/lastlog</tt> file. Adding +an open entry when called via the <tt>pam_open_seesion()</tt> function +and completing it when <tt>pam_close_session()</tt> is called. This +module can also display a line of information about the last login of +the user. If an application already performs these tasks, it is not +necessary to use this module. + +<sect2>Authentication component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +<tt/debug/; <tt/nodate/; <tt/noterm/; <tt/nohost/; <tt/silent/; +<tt/never/ + +<tag><bf>Description:</bf></tag> + +<p> +This module can be used to provide a ``Last login on ...'' +message. when the user logs into the system from what ever application +uses the PAM libraries. In addition, the module maintains the +<tt>/var/log/lastlog</tt> file. + +<p> +The behavior of this module can be modified with one of the following +flags: + +<p> +<itemize> +<item><tt/debug/ +- write more information to <tt/syslog(3)/. + +<item><tt/nodate/ +- neglect to give the date of the last login when displaying +information about the last login on the system. + +<item><tt/noterm/ +- neglect to diplay the terminal name on which the last login was +attempt. + +<item><tt/nohost/ +- neglect to indicate from which host the last login was attempted. + +<item><tt/silent/ +- neglect to inform the user about any previous login: just update +the <tt>/var/log/lastlog</tt> file. + +<item><tt/never/ +- if the <tt>/var/log/lastlog</tt> file does not contain any old entries +for the user, indicate that the user has never previously logged in +with a ``welcome..." message. + +</itemize> + +<tag><bf>Examples/suggested usage:</bf></tag> + +This module can be used to indicate that the user has new mail when +they <em/login/ to the system. Here is a sample entry for your +<tt>/etc/pam.conf</tt> file: +<tscreen> +<verb> +# +# do we have any mail? +# +login session optional pam_lastlog.so +</verb> +</tscreen> + +<p> +Note, some applications may perform this function themselves. In such +cases, this module is not necessary. + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/modules/pam_limits.sgml b/doc/modules/pam_limits.sgml new file mode 100644 index 00000000..f7a2245e --- /dev/null +++ b/doc/modules/pam_limits.sgml @@ -0,0 +1,197 @@ +<!-- + $Id$ + + This file was written by Andrew G. Morgan <morgan@parc.power.net> + from information compiled by Cristian Gafton (author of module) +--> + +<sect1>The resource limits module + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +<tt/pam_limits/ + +<tag><bf>Authors:</bf></tag> +Cristian Gafton <gafton@redhat.com> <newline> +Thanks are also due to Elliot Lee <sopwith@redhat.com> +for his comments on improving this module. + +<tag><bf>Maintainer:</bf></tag> +Cristian Gafton - 1996/11/20 + +<tag><bf>Management groups provided:</bf></tag> +session + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> + +<tag><bf>System dependencies:</bf></tag> +requires an <tt>/etc/security/limits.conf</tt> file and kernel support +for resource limits. Also uses the library, <tt/libpwdb/. + +<tag><bf>Network aware:</bf></tag> + +</descrip> + +<sect2>Overview of module + +<p> +This module, through the <bf/Linux-PAM/ <em/open/-session hook, sets +limits on the system resources that can be obtained in a +user-session. Its actions are dictated more explicitly through the +configuration file discussed below. + +<sect2>Session component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +<tt/debug/; <tt>conf=/path/to/file.conf</tt> + +<tag><bf>Description:</bf></tag> + +Through the contents of the configuration file, +<tt>/etc/security/limits.conf</tt>, resource limits are placed on +users' sessions. Users of <tt/uid=0/ are not affected by this +restriction. + +<p> +The behavior of this module can be modified with the following +arguments: +<itemize> + +<item><tt/debug/ - +verbose logging to <tt/syslog(3)/. + +<item><tt>conf=/path/to/file.conf</tt> - +indicate an alternative <em/limits/ configuration file to the default. + +</itemize> + +<tag><bf>Examples/suggested usage:</bf></tag> + +In order to use this module the system administrator must first create +a <em/root-only-readable/ file (default is +<tt>/etc/security/limits.conf</tt>). This file describes the resource +limits the superuser wishes to impose on users and groups. No limits +are imposed on <tt/uid=0/ accounts. + +<p> +Each line of the configuration file describes a limit for a user in +the form: +<tscreen> +<verb> +<domain> <type> <item> <value> +</verb> +</tscreen> + +<p> +The fields listed above should be filled as follows...<newline> +<tt><domain></tt> can be: +<itemize> +<item> a username +<item> a groupname, with <tt>@group</tt> syntax +<item> the wild-card <tt/*/, for default entry +</itemize> + +<p> +<tt><type></tt> can have the two values: +<itemize> + +<item> <tt/hard/ for enforcing <em/hard/ resource limits. These limits +are set by the superuser and enforced by the Linux Kernel. The user +cannot raise his requirement of system resources above such values. + +<item> <tt/soft/ for enforcing <em/soft/ resource limits. These limits +are ones that the user can move up or down within the permitted range +by any pre-exisiting <em/hard/ limits. The values specified with this +token can be thought of as <em/default/ values, for normal system +usage. + +</itemize> + +<p> +<tt><item></tt> can be one of the following: +<itemize> +<item><tt/core/ - limits the core file size (KB) +<item><tt/data/ - max data size (KB) +<item><tt/fsize/ - maximum filesize (KB) +<item><tt/memlock/ - max locked-in-memory address space (KB) +<item><tt/nofile/ - max number of open files +<item><tt/rss/ - max resident set size (KB) +<item><tt/stack/ - max stack size (KB) +<item><tt/cpu/ - max CPU time (MIN) +<item><tt/nproc/ - max number of processes +<item><tt/as/ - address space limit +<item><tt/maxlogins/ - max number of logins for this user. +<item><tt/priority/ - the priority to run user process with +</itemize> + +<p> +To completely disable limits for a user (or a group), a single dash +(-) will do (Example: ``<tt/bin -/'', ``<tt/@admin -/''). Please +remember that individual limits have priority over group limits, so if +you impose no limits for <tt/admin/ group, but one of the members in this +group have a limits line, the user will have its limits set according +to this line. + +<p> +Also, please note that all limit settings are set <em/per login/. +They are not global, nor are they permanent; existing only for the +duration of the session. + +<p> +In the <em/limits/ configuration file, the ``<tt/#/'' character +introduces a comment - after which the rest of the line is ignored. + +<p> +The <tt/pam_limits/ module does its best to report configuration +problems found in its configuration file via <tt/syslog(3)/. + +<p> +The following is an example configuration file: +<tscreen> +<verb> +# EXAMPLE /etc/security/limits.conf file: +# ======================================= +# <domain> <type> <item> <value> +* soft core 0 +* hard rss 10000 +@student hard nproc 20 +@faculty soft nproc 20 +@faculty hard nproc 50 +ftp hard nproc 0 +@student - maxlogins 4 +</verb> +</tscreen> +Note, the use of <tt/soft/ and <tt/hard/ limits for the same resource +(see <tt/@faculty/) -- this establishes the <em/default/ and permitted +<em/extreme/ level of resources that the user can can obtain in a +given service-session. + +<p> +For the services that need resources limits (login for example) put a +the following line in <tt>/etc/pam.conf</tt> as the last line for that +service (usually after the pam_unix session line: +<tscreen> +<verb> +# +# Resource limits imposed on login sessions via pam_limits +# +login session required pam_limits.so +</verb> +</tscreen> + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/modules/pam_listfile.sgml b/doc/modules/pam_listfile.sgml new file mode 100644 index 00000000..98589a3b --- /dev/null +++ b/doc/modules/pam_listfile.sgml @@ -0,0 +1,138 @@ +<!-- + $Id$ + + This file was written by Michael K. Johnson <johnsonm@redhat.com> +--> + +<sect1>The list-file module + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +<tt/pam_listfile/ + +<tag><bf>Author:</bf></tag> +Elliot Lee <tt><sopwith@cuc.edu></tt> + +<tag><bf>Maintainer:</bf></tag> +Red Hat Software:<newline> +Michael K. Johnson <johnsonm@redhat.com> 1996/11/18<newline> +(if unavailable, contact Elliot Lee <sopwith@cuc.edu>). + +<tag><bf>Management groups provided:</bf></tag> +authentication + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> +clean + +<tag><bf>System dependencies:</bf></tag> + +<tag><bf>Network aware:</bf></tag> + +</descrip> + +<sect2>Overview of module + +<p> +The list-file module provides a way to deny or allow services based on +an arbitrary file. + +<sect2>Authentication component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> + +<tt>onerr=succeed|fail</tt>; +<tt>sense=allow|deny</tt>; +<tt>file=</tt><it>filename</it>; +<tt>item=user|tty|rhost|ruser|group|shell</tt> +<tt>apply=user|@group</tt> + +<tag><bf>Description:</bf></tag> + +The module gets the item of the type specified -- <tt>user</tt> specifies +the username, <tt>PAM_USER</tt>; tty specifies the name of the terminal +over which the request has been made, <tt>PAM_TTY</tt>; rhost specifies +the name of the remote host (if any) from which the request was made, +<tt>PAM_RHOST</tt>; and ruser specifies the name of the remote user +(if available) who made the request, <tt>PAM_RUSER</tt> -- and looks for +an instance of that item in the file <it>filename</it>. <it>filename</it> +contains one line per item listed. If the item is found, then if +<tt>sense=allow</tt>, <tt>PAM_SUCCESS</tt> is returned, causing the +authorization request to succeed; else if <tt>sense=deny</tt>, +<tt>PAM_AUTH_ERR</tt> is returned, causing the authorization +request to fail. + +<p> +If an error is encountered (for instance, if <it>filename</it> +does not exist, or a poorly-constructed argument is encountered), +then if <tt>onerr=succeed</tt>, <tt>PAM_SUCCESS</tt> is returned, +otherwise if <tt>onerr=fail</tt>, <tt>PAM_AUTH_ERR</tt> or +<tt>PAM_SERVICE_ERR</tt> (as appropriate) will be returned. + +<p> +An additional argument, <tt>apply=</tt>, can be used to restrict the +application of the above to a specific user +(<tt>apply=</tt><em>username</em>) or a given group +(<tt>apply=@</tt><em>groupname</em>). This added restriction is only +meaningful when used with the <tt/tty/, <tt/rhost/ and <tt/shell/ +<em/items/. + +<p> +Besides this last one, all arguments should be specified; do not count +on any default behavior, as it is subject to change. + +<p> +No credentials are awarded by this module. + +<tag><bf>Examples/suggested usage:</bf></tag> + +Classic ``ftpusers'' authentication can be implemented with this entry +in <tt>/etc/pam.conf</tt>: +<tscreen> +<verb> +# +# deny ftp-access to users listed in the /etc/ftpusers file +# +ftp auth required pam_listfile.so \ + onerr=succeed item=user sense=deny file=/etc/ftpusers +</verb> +</tscreen> +Note, users listed in <tt>/etc/ftpusers</tt> file are +(counterintuitively) <bf/not/ allowed access to the ftp service. + +<p> +To allow login access only for certain users, you can use an +pam.conf entry like this: +<tscreen> +<verb> +# +# permit login to users listed in /etc/loginusers +# +login auth required pam_listfile.so \ + onerr=fail item=user sense=allow file=/etc/loginusers +</verb> +</tscreen> + +<p> +For this example to work, all users who are allowed to use the login +service should be listed in the file <tt>/etc/loginusers</tt>. Unless +you are explicitly trying to lock out root, make sure that when you do +this, you leave a way for root to log in, either by listing root in +<tt>/etc/loginusers</tt>, or by listing a user who is able to <em/su/ +to the root account. + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/modules/pam_mail.sgml b/doc/modules/pam_mail.sgml new file mode 100644 index 00000000..064b9ffa --- /dev/null +++ b/doc/modules/pam_mail.sgml @@ -0,0 +1,137 @@ +<!-- + $Id$ + + This file was written by Andrew G. Morgan <morgan@linux.kernel.org> +--> + +<sect1>The mail module + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +<tt/pam_mail/ + +<tag><bf>Author:</bf></tag> +Andrew G. Morgan <morgan@linux.kernel.org> + +<tag><bf>Maintainer:</bf></tag> +Author + +<tag><bf>Management groups provided:</bf></tag> +Authentication (credential) +Session (open) + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> + +<tag><bf>System dependencies:</bf></tag> +Default mail directory <tt>/var/spool/mail/</tt> + +<tag><bf>Network aware:</bf></tag> + +</descrip> + +<sect2>Overview of module + +<p> +This module looks at the user's mail directory and indicates +whether the user has any mail in it. + +<sect2>Session component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +<tt/debug/; <tt/dir=/<em/direcory-name/; <tt/nopen/; <tt/close/; +<tt/noenv/; <tt/empty/; <tt/hash=/<em/hashcount/; <tt/standard/; +<tt/quiet/; + +<tag><bf>Description:</bf></tag> + +This module provides the ``you have new mail'' service to the user. It +can be plugged into any application that has credential hooks. It gives a +single message indicating the <em/newness/ of any mail it finds in the +user's mail folder. This module also sets the <bf/Linux-PAM/ +environment variable, <tt/MAIL/, to the user's mail directory. + +<p> +The behavior of this module can be modified with one of the following +flags: + +<p> +<itemize> +<item><tt/debug/ +- write more information to <tt/syslog(3)/. + +<item><tt/dir=/<em/pathname/ +- look for the users' mail in an alternative directory given by +<em/pathname/. The default location for mail is +<tt>/var/spool/mail</tt>. Note, if the supplied <em/pathname/ is +prefixed by a `<tt/˜/', the directory is interpreted as +indicating a file in the user's home directory. + +<item><tt/nopen/ +- instruct the module to <em/not/ print any mail information when the +user's credentials are acquired. This flag is useful to get the <tt/MAIL/ +environment variable set, but to not display any information about it. + +<item><tt/close/ +- instruct the module to indicate if the user has any mail at the as +the user's credentials are revoked. + +<item><tt/noenv/ +- do not set the <tt/MAIL/ environment variable. + +<item><tt/empty/ +- indicate that the user's mail directory is empty if this is found to +be the case. + +<item><tt/hash=/<em/hashcount/ +- mail directory hash depth. For example, a <em/hashcount/ of 2 would +make the mailfile be <tt>/var/spool/mail/u/s/user</tt>. + +<item><tt/standard/ +- old style "You have..." format which doesn't show the mail spool being used. + this also implies "empty" + +<item><tt/quiet/ +- only report when there is new mail. + +</itemize> + +<tag><bf>Examples/suggested usage:</bf></tag> + +This module can be used to indicate that the user has new mail when +they <em/login/ to the system. Here is a sample entry for your +<tt>/etc/pam.conf</tt> file: +<tscreen> +<verb> +# +# do we have any mail? +# +login session optional pam_mail.so +</verb> +</tscreen> + +<p> +Note, some applications may perform this function themselves. In such +cases, this module is not necessary. + +</descrip> + +<sect2>Authentication compent + +<p> +Then authentication companent works the same as the session component, +expect that everything is done during the pam_setcred() phase. + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/modules/pam_mkhomedir.sgml b/doc/modules/pam_mkhomedir.sgml new file mode 100644 index 00000000..075e16f9 --- /dev/null +++ b/doc/modules/pam_mkhomedir.sgml @@ -0,0 +1,83 @@ +<!-- + +Ben Collins <bcollins@debian.org> + +--> + +<sect1>Create home directories on initial login + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +<tt/pam_mkhomedir/ + +<tag><bf>Author:</bf></tag> +Jason Gunthorpe <jgg@ualberta.ca> + +<tag><bf>Maintainer:</bf></tag> +Ben Collins <bcollins@debian.org> + +<tag><bf>Management groups provided:</bf></tag> +Session + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> + +<tag><bf>System dependencies:</bf></tag> + +<tag><bf>Network aware:</bf></tag> + +</descrip> + +<sect2>Overview of module + +<p> +Creates home directories on the fly for authenticated users. + +<sect2>Session component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +<tt/debug/; <tt/skel=skeleton-dir/; <tt/umask=octal-umask/; + +<tag><bf>Description:</bf></tag> +This module is useful for distributed systems where the user account is +managed in a central database (such as NIS, NIS+, or LDAP) and accessed +through miltiple systems. It frees the administrator from having to create +a default home directory on each of the systems by creating it upon the +first succesfully authenticated login of that user. The skeleton directory +(usually /etc/skel/) is used to copy default files and also set's a umask +for the creation. + +<p> +The behavior of this module can be modified with one of the following +flags: + +<p> +<itemize> + +<item><tt/skel/ +- The skeleton directory for default files to copy to the new home directory. + +<item><tt/umask/ +- An octal for of the same format as you would pass to the shells umask command. + +</itemize> + +<tag><bf>Examples/suggested usage:</bf></tag> + +session required pam_mkhomedir.so skel=/etc/skel/ umask=0022 + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/modules/pam_motd.sgml b/doc/modules/pam_motd.sgml new file mode 100644 index 00000000..1f8fc393 --- /dev/null +++ b/doc/modules/pam_motd.sgml @@ -0,0 +1,77 @@ +<!-- + +Ben Collins <bcollins@debian.org> + +--> + +<sect1>Output the motd file + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +<tt/pam_motd/ + +<tag><bf>Author:</bf></tag> +Ben Collins <bcollins@debian.org> + +<tag><bf>Maintainer:</bf></tag> +Author + +<tag><bf>Management groups provided:</bf></tag> +Session (open) + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> + +<tag><bf>System dependencies:</bf></tag> + +<tag><bf>Network aware:</bf></tag> + +</descrip> + +<sect2>Overview of module + +<p> +This module outputs the motd file (<em>/etc/motd</em> by default) upon succesful +login. + +<sect2>Session component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +<tt/debug/; <tt/motd=motd-file-name/; + +<tag><bf>Description:</bf></tag> +This module allows you to have arbitrary motd's (message of the day) +output after a succesful login. By default this file is <em>/etc/motd</em>, +but is configurable to any file. + +<p> +The behavior of this module can be modified with one of the following +flags: + +<p> +<itemize> + +<item><tt/motd/ +- the file to output if not using the default. + +</itemize> + +<tag><bf>Examples/suggested usage:</bf></tag> + +login session pam_motd.so motd=/etc/motd + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/modules/pam_nologin.sgml b/doc/modules/pam_nologin.sgml new file mode 100644 index 00000000..90564d89 --- /dev/null +++ b/doc/modules/pam_nologin.sgml @@ -0,0 +1,75 @@ +<!-- + $Id$ + + This file was written by Michael K. Johnson <johnsonm@redhat.com> +--> + +<sect1>The no-login module + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +<tt/pam_nologin/ + +<tag><bf>Author:</bf></tag> +Written by Michael K. Johnson <johnsonm@redhat.com><newline> +(based on code taken from a module written by Andrew G. Morgan +<morgan@parc.power.net>). + +<tag><bf>Maintainer:</bf></tag> +Michael K. Johnson <johnsonm@redhat.com> + +<tag><bf>Management groups provided:</bf></tag> +authentication + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> +1 warning about dropping const + +<tag><bf>System dependencies:</bf></tag> + +<tag><bf>Network aware:</bf></tag> + +</descrip> + +<sect2>Overview of module + +<p> +Provides standard Unix <em/nologin/ authentication. + +<sect2>Authentication component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> + +<tag><bf>Description:</bf></tag> + +Provides standard Unix <em/nologin/ authentication. If the file +<tt>/etc/nologin</tt> exists, only root is allowed to log in; other +users are turned away with an error message. All users (root or +otherwise) are shown the contents of <tt>/etc/nologin</tt>. + +<p> +If the file <tt>/etc/nologin</tt> does not exist, this module succeeds +silently. + +<tag><bf>Examples/suggested usage:</bf></tag> + +In order to make this module effective, all login methods should +be secured by it. It should be used as a <tt>required</tt> +method listed before any <tt>sufficient</tt> methods in order to +get standard Unix nologin semantics. + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/modules/pam_permit.sgml b/doc/modules/pam_permit.sgml new file mode 100644 index 00000000..8b201b7c --- /dev/null +++ b/doc/modules/pam_permit.sgml @@ -0,0 +1,83 @@ +<!-- + $Id$ + + This file was written by Andrew G. Morgan <morgan@parc.power.net> +--> + +<sect1>The promiscuous module + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +pam_permit + +<tag><bf>Author:</bf></tag> +Andrew G. Morgan, <morgan@parc.power.net> + +<tag><bf>Maintainer:</bf></tag> +Linux-PAM maintainer. + +<tag><bf>Management groups provided:</bf></tag> +account; authentication; password; session + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> +VERY LOW. Use with extreme caution. + +<tag><bf>Clean code base:</bf></tag> +Clean. + +<tag><bf>System dependencies:</bf></tag> + +<tag><bf>Network aware:</bf></tag> + +</descrip> + +<sect2>Overview of module + +<p> +This module is very dangerous. It should be used with extreme +caution. Its action is always to permit access. It does nothing else. + +<sect2>Account+Authentication+Password+Session components + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> + +<tag><bf>Description:</bf></tag> + +No matter what management group, the action of this module is to +simply return <tt/PAM_SUCCESS/ -- operation successful. + +<p> +In the case of authentication, the user's name will be acquired. Many +applications become confused if this name is unknown. + +<tag><bf>Examples/suggested usage:</bf></tag> + +It is seldom a good idea to use this module. However, it does have +some legitimate uses. For example, if the system-administrator wishes +to turn off the account management on a workstation, and at the same +time continue to allow logins, then she might use the following +configuration file entry for login: +<tscreen> +<verb> +# +# add this line to your other login entries to disable account +# management, but continue to permit users to log in... +# +login account required pam_permit.so +</verb> +</tscreen> + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/modules/pam_pwdb.sgml b/doc/modules/pam_pwdb.sgml new file mode 100644 index 00000000..022cfe57 --- /dev/null +++ b/doc/modules/pam_pwdb.sgml @@ -0,0 +1,252 @@ +<!-- + $Id$ + + This file was written by Andrew G. Morgan <morgan@linux.kernel.org> +--> + +<sect1>The Password-Database module + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +pam_pwdb + +<tag><bf>Author:</bf></tag> +Cristian Gafton <gafton@redhat.com> <newline> +and Andrew G. Morgan <morgan@linux.kernel.org> + +<tag><bf>Maintainer:</bf></tag> +Authors. + +<tag><bf>Management groups provided:</bf></tag> +account; authentication; password; session + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> + +<tag><bf>System dependencies:</bf></tag> +Requires properly configured <tt/libpwdb/ + +<tag><bf>Network aware:</bf></tag> + +</descrip> + +<sect2>Overview of module + +<p> +This module is a pluggable replacement for the <tt/pam_unix_../ +modules. It uses the generic interface of the <em/Password Database/ +library +<tt><htmlurl +url="http://linux.kernel.org/morgan/libpwdb/index.html" +name="http://linux.kernel.org/morgan/libpwdb/index.html"></tt>. + +<sect2>Account component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +<tt/debug/ + +<tag><bf>Description:</bf></tag> + +The <tt/debug/ argument makes the accounting functions of this module +<tt/syslog(3)/ more information on its actions. (Remaining arguments +supported by the other functions of this module are silently ignored, +but others are logged as errors through <tt/syslog(3)/). + +Based on the following <tt/pwdb_element/s: +<tt/expire/; +<tt/last_change/; +<tt/max_change/; +<tt/defer_change/; +<tt/warn_change/, +this module performs the task of establishing the status of the user's +account and password. In the case of the latter, it may offer advice +to the user on changing their password or, through the +<tt/PAM_AUTHTOKEN_REQD/ return, delay giving service to the user until +they have established a new password. The entries listed above are +documented in the <em/Password Database Library Guide/ (see pointer +above). Should the user's record not contain one or more of these +entries, the corresponding <em/shadow/ check is not performed. + +<tag><bf>Examples/suggested usage:</bf></tag> + +In its accounting mode, this module can be inserted as follows: +<tscreen> +<verb> +# +# Ensure users account and password are still active +# +login account required pam_pwdb.so +</verb> +</tscreen> + +</descrip> + +<sect2>Authentication component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +<tt/debug/; +<tt/use_first_pass/; +<tt/try_first_pass/; +<tt/nullok/; +<tt/nodelay/; +<tt/likeauth/ + +<tag><bf>Description:</bf></tag> + +The <tt/debug/ argument makes the authentication functions of this +module <tt/syslog(3)/ more information on its actions. + +<p> +The default action of this module is to not permit the user access to +a service if their <em/official/ password is blank. The <tt/nullok/ +argument overrides this default. + +<p> +When given the argument <tt/try_first_pass/, before prompting the user +for their password, the module first tries the previous stacked +<tt/auth/-module's password in case that satisfies this module as +well. The argument <tt/use_first_pass/ forces the module to use such a +recalled password and will never prompt the user - if no password is +available or the password is not appropriate, the user will be denied +access. + +<p> +The argument, <tt>nodelay</tt>, can be used to discourage the +authentication component from requesting a delay should the +authentication as a whole fail. The default action is for the module +to request a delay-on-failure of the order of one second. + +<p> +Remaining arguments, supported by the other functions of this module, +are silently ignored. Other arguments are logged as errors through +<tt/syslog(3)/. + +<p> +A helper binary, <tt>pwdb_chkpwd</tt>, is provided to check the user's +password when it is stored in a read protected database. This binary +is very simple and will only check the password of the user invoking +it. It is called transparently on behalf of the user by the +authenticating component of this module. In this way it is possible +for applications like <em>xlock</em> to work without being setuid-root. + +<p> +The <tt>likeauth</tt> argument makes the module return the same value +when called as a credential setting module and an authentication +module. This will help libpam take a sane path through the auth +component of your configuration file. + +<tag><bf>Examples/suggested usage:</bf></tag> + +The correct functionality of this module is dictated by having an +appropriate <tt>/etc/pwdb.conf</tt> file, the user +databases specified there dictate the source of the authenticated +user's record. + +</descrip> + +<sect2>Password component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +<tt/debug/; <tt/nullok/; <tt/not_set_pass/; <tt/use_authtok/; +<tt/try_first_pass/; <tt/use_first_pass/; <tt/md5/; <tt/bigcrypt/; +<tt/shadow/; <tt/radius/; <tt/unix/ + +<tag><bf>Description:</bf></tag> + +This part of the <tt/pam_pwdb/ module performs the task of updating +the user's password. Thanks to the flexibility of <tt/libpwdb/ this +module is able to move the user's password from one database to +another, perhaps securing the user's database entry in a dynamic +manner (<em/this is very ALPHA code at the moment!/) - this is the +purpose of the <tt/shadow/, <tt/radius/ and <tt/unix/ arguments. + +<p> +In the case of conventional unix databases (which store the password +encrypted) the <tt/md5/ argument is used to do the encryption with the +MD5 function as opposed to the <em/conventional/ <tt/crypt(3)/ call. +As an alternative to this, the <tt/bigcrypt/ argument can be used to +encrypt more than the first 8 characters of a password with DEC's +(Digital Equipment Cooperation) `C2' extension to the standard UNIX +<tt/crypt()/ algorithm. + +<p> +The <tt/nullok/ module is used to permit the changing of a password +<em/from/ an empty one. Without this argument, empty passwords are +treated as account-locking ones. + +<p> +The argument <tt/use_first_pass/ is used to lock the choice of old and +new passwords to that dictated by the previously stacked <tt/password/ +module. The <tt/try_first_pass/ argument is used to avoid the user +having to re-enter an old password when <tt/pam_pwdb/ follows a module +that possibly shared the user's old password - if this old password is +not correct the user will be prompted for the correct one. The +argument <tt/use_authtok/ is used to <em/force/ this module to set the +new password to the one provided by the previously stacked +<tt/password/ module (this is used in an example of the stacking of +the <em/Cracklib/ module documented above). + +<p> +The <tt/not_set_pass/ argument is used to inform the module that it is +not to pay attention to/make available the old or new passwords from/to +other (stacked) password modules. + +<p> +The <tt/debug/ argument makes the password functions of this module +<tt/syslog(3)/ more information on its actions. Other arguments may be +logged as erroneous to <tt/syslog(3)/. + +<tag><bf>Examples/suggested usage:</bf></tag> + +An example of the stacking of this module with respect to the +pluggable password checking module, <tt/pam_cracklib/, is given in +that modules section above. +</descrip> + +<sect2>Session component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> + +<tag><bf>Description:</bf></tag> + +No arguments are recognized by this module component. Its action is +simply to log the username and the service-type to +<tt/syslog(3)/. Messages are logged at the beginning and end of the +user's session. + +<tag><bf>Examples/suggested usage:</bf></tag> + +The use of the session modules is straightforward: +<tscreen> +<verb> +# +# pwdb - unix like session opening and closing +# +login session required pam_pwdb.so +</verb> +</tscreen> + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/modules/pam_radius.sgml b/doc/modules/pam_radius.sgml new file mode 100644 index 00000000..fb442ee3 --- /dev/null +++ b/doc/modules/pam_radius.sgml @@ -0,0 +1,117 @@ +<!-- + $Id$ + + This file was written by Cristian Gafton <gafton@redhat.com> +--> + +<sect1>The RADIUS session module + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +<tt/pam_radius/ + +<tag><bf>Author:</bf></tag> +Cristian Gafton <gafton@redhat.com> + +<tag><bf>Maintainer:</bf></tag> +Author. + +<tag><bf>Management groups provided:</bf></tag> +session + +<tag><bf>Cryptographically sensitive:</bf></tag> +This module does not deal with passwords + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> +gcc reports 1 warning when compiling <tt>/usr/include/rpc/clnt.h</tt>. +Hey, is not my fault ! + +<tag><bf>System dependencies:</bf></tag> + +<tag><bf>Network aware:</bf></tag> + +yes; this is a network module (independent of application). + +</descrip> + +<sect2>Overview of module + +<p> +This module is intended to provide the session service for users +autheticated with a RADIUS server. At the present stage, the only +option supported is the use of the RADIUS server as an accounting +server. + +<sect2>Session component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> + +<tt/debug/ - verbose logging to <tt/syslog(3)/. + +<tag><bf>Description:</bf></tag> + +This module is intended to provide the session service for users +autheticated with a RADIUS server. At the present stage, the only +option supported is the use of the RADIUS server as an <em/accounting/ +server. + +<p> +(There are few things which needs to be cleared out first in +the PAM project until one will be able to use this module and expect +it to magically start pppd in response to a RADIUS server command to +use PPP for this user, or to initiate a telnet connection to another +host, or to hang and call back the user using parameters provided in +the RADIUS server response. Most of these things are better suited for +the radius login application. I hope to make available Real Soon (tm) +patches for the login apps to make it work this way.) + +<p> +When opening a session, this module sends an ``Accounting-Start'' +message to the RADIUS server, which will log/update/whatever a +database for this user. On close, an ``Accounting-Stop'' message is +sent to the RADIUS server. + +<p> +This module has no other prerequisites for making it work. One can +install a RADIUS server just for fun and use it as a centralized +accounting server and forget about wtmp/last/sac etc. . + +<tag><bf>Examples/suggested usage:</bf></tag> + +For the services that need this module (<em/login/ for example) put +the following line in <tt>/etc/pam.conf</tt> as the last line for that +service (usually after the pam_unix session line): +<tscreen> +<verb> +login session required pam_radius.so +</verb> +</tscreen> +Replace <tt/login/ for each service you are using this module. + +<p> +This module make extensive use of the API provided in libpwdb +0.54preB or later. By default, it will read the radius server +configuration (hostname and secret) from <tt>/etc/raddb/server</tt>. +This is a default compiled into libpwdb, and curently there is no way to +modify this default without recompiling libpwdb. I am working on +extending the radius support from libpwdb to provide a possibility +to make this runtime-configurable. + +Also please note that libpwdb will require also the RADIUS +dictionary to be present (<tt>/etc/raddb/dictionary</tt>). + +</descrip> + +<!-- +End of sgml insert for this module. +--> + diff --git a/doc/modules/pam_rhosts.sgml b/doc/modules/pam_rhosts.sgml new file mode 100644 index 00000000..00e55a9d --- /dev/null +++ b/doc/modules/pam_rhosts.sgml @@ -0,0 +1,164 @@ +<!-- + $Id$ + + This file was written by Andrew G. Morgan <morgan@parc.power.net> +--> + +<sect1>The rhosts module + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +<tt/pam_rhosts_auth/ + +<tag><bf>Author:</bf></tag> +Al Longyear <longyear@netcom.com> + +<tag><bf>Maintainer:</bf></tag> + +<tag><bf>Management groups provided:</bf></tag> +authentication + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> +Clean. + +<tag><bf>System dependencies:</bf></tag> + +<tag><bf>Network aware:</bf></tag> +Standard <tt/inet_addr()/, <tt/gethostbyname()/ function calls. + +</descrip> + +<sect2>Overview of module + +<p> +This module performs the standard network authentication for services, +as used by traditional implementations of <em/rlogin/ and <em/rsh/ +etc. + +<sect2>Authentication component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +<tt/no_hosts_equiv/; <tt/no_rhosts/; <tt/debug/; <tt/no_warn/; +<tt/privategroup/; <tt/promiscuous/; <tt/suppress/ + +<tag><bf>Description:</bf></tag> + +The authentication mechanism of this module is based on the contents +of two files; <tt>/etc/hosts.equiv</tt> (or <tt/_PATH_HEQUIV/ in +<tt>#include <netdb.h></tt>) and <tt>~/.rhosts</tt>. Firstly, +hosts listed in the former file are treated as equivalent to the +localhost. Secondly, entries in the user's own copy of the latter file +is used to map "<tt/remote-host remote-user/" pairs to that user's +account on the current host. Access is granted to the user if their +host is present in <tt>/etc/hosts.equiv</tt> and their remote account +is identical to their local one, or if their remote account has an +entry in their personal configuration file. + +<p> +Some restrictions are applied to the attributes of the user's personal +configuration file: it must be a regular file (as defined by +<tt/S_ISREG(x)/ of POSIX.1); it must be owned by the <em/superuser/ or +the user; it must not be writable by any user besides its owner. + +<p> +The module authenticates a remote user (internally specified by the +item <tt/PAM_RUSER/) connecting from the remote host (internally +specified by the item <tt/PAM_RHOST/). Accordingly, for applications +to be compatible this authentication module they must set these items +prior to calling <tt/pam_authenticate()/. The module is not capable +of independently probing the network connection for such information. + +<p> +In the case of <tt/root/-access, the <tt>/etc/host.equiv</tt> file is +<em/ignored/ unless the <tt>hosts_equiv_rootok</tt> option +should be used. Instead, the superuser must have a correctly configured +personal configuration file. + +<p> +The behavior of the module is modified by flags: +<itemize> +<item> +<tt/debug/ - +log more information to <tt/syslog(3)/. (XXX - actually, this module +does not do any logging currently, please volunteer to fix this!) + +<item> +<tt/no_warn/ - +do not give verbal warnings to the user about failures etc. (XXX - +this module currently does not issue any warnings, please volunteer to +fix this!) + +<item> +<tt/no_hosts_equiv/ - +ignore the contents of the <tt>/etc/hosts.equiv</tt> file. + +<item> +<tt/hosts_equiv_rootok/ - +allow the use of <tt>/etc/hosts.equiv</tt> for superuser. Without this +option <tt>/etc/hosts.equiv</tt> is not consulted for the superuser account. +This option has no effect if the <tt>no_hosts_equiv</tt> option is used. + +<item> +<tt/no_rhosts/ - +ignore the contents of all user's personal configuration file +<tt>~/.rhosts</tt>. + +<item> +<tt/privategroup/ - +normally, the <tt>~/.rhosts</tt> file must not be writable by anyone +other than its owner. This option overlooks group write access in the +case that the group owner of this file has the same name as the +user being authenticated. To lessen the security problems associated +with this option, the module also checks that the user is the only +member of their private group. + +<item> +<tt/promiscuous/ - +A host entry of `+' will lead to all hosts being granted +access. Without this option, '+' entries will be ignored. Note, that +the <tt/debug/ option will syslog a warning in this latter case. + +<item> +<tt/suppress/ - +This will prevent the module from <tt/syslog(3)/ing a warning message +when this authentication fails. This option is mostly for keeping +logs free of meaningless errors, in particular when the module is used +with the <tt/sufficient/ control flag. + +</itemize> +<tag><bf>Examples/suggested usage:</bf></tag> + +To allow users to login from trusted remote machines, you should try +adding the following line to your <tt>/etc/pam.conf</tt> file +<em/before/ the line that would otherwise prompt the user for a +password: +<tscreen> +<verb> +# +# No passwords required for users from hosts listed above. +# +login auth sufficient pam_rhosts_auth.so no_rhosts +</verb> +</tscreen> +Note, in this example, the system administrator has turned off all +<em/personal/ <em/rhosts/ configuration files. Also note, that this module +can be used to <em/only/ allow remote login from hosts specified in +the <tt>/etc/host.equiv</tt> file, by replacing <tt/sufficient/ in the +above example with <tt/required/. + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/modules/pam_rootok.sgml b/doc/modules/pam_rootok.sgml new file mode 100644 index 00000000..e362a2a5 --- /dev/null +++ b/doc/modules/pam_rootok.sgml @@ -0,0 +1,85 @@ +<!-- + $Id$ + + This file was written by Andrew G. Morgan <morgan@parc.power.net> +--> + +<sect1>The root access module + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +pam_rootok + +<tag><bf>Author:</bf></tag> +Andrew G. Morgan <morgan@parc.power.net> + +<tag><bf>Maintainer:</bf></tag> +<bf>Linux-PAM</bf> maintainer + +<tag><bf>Management groups provided:</bf></tag> +authentication + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> +Clean. + +<tag><bf>System dependencies:</bf></tag> + +<tag><bf>Network aware:</bf></tag> + +</descrip> + +<sect2>Overview of module + +<p> +This module is for use in situations where the superuser wishes +to gain access to a service without having to enter a password. + +<sect2>Authentication component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +<tt/debug/ + +<tag><bf>Description:</bf></tag> + +This module authenticates the user if their <tt/uid/ is <tt/0/. +Applications that are created <em/setuid/-root generally retain the +<tt/uid/ of the user but run with the authority of an enhanced +<em/effective-/<tt/uid/. It is the real <tt/uid/ that is checked. + +<tag><bf>Examples/suggested usage:</bf></tag> + +In the case of the <tt/su/ application the historical usage is to +permit the superuser to adopt the identity of a lesser user without +the use of a password. To obtain this behavior under <tt/Linux-PAM/ +the following pair of lines are needed for the corresponding entry in +the configuration file: +<tscreen> +<verb> +# +# su authentication. Root is granted access by default. +# +su auth sufficient pam_rootok.so +su auth required pam_unix_auth.so +</verb> +</tscreen> + +<p> +Note. For programs that are run by the superuser (or started when the +system boots) this module should not be used to authenticate users. + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/modules/pam_securetty.sgml b/doc/modules/pam_securetty.sgml new file mode 100644 index 00000000..ceb1358c --- /dev/null +++ b/doc/modules/pam_securetty.sgml @@ -0,0 +1,72 @@ +<!-- + $Id$ + + This file was written by Michael K. Johnson <johnsonm@redhat.com> +--> + +<sect1>The securetty module + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +<tt/pam_securetty/ + +<tag><bf>Author[s]:</bf></tag> +Elliot Lee <sopwith@cuc.edu> + +<tag><bf>Maintainer:</bf></tag> +Red Hat Software:<newline> +<em/currently/ Michael K. Johnson <johnsonm@redhat.com><newline> +(if unavailable, contact Elliot Lee <sopwith@cuc.edu>). + +<tag><bf>Management groups provided:</bf></tag> +authentication + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> + +<tag><bf>System dependencies:</bf></tag> +<tt>/etc/securetty</tt> file + +<tag><bf>Network aware:</bf></tag> + +Requires the application to fill in the <tt>PAM_TTY</tt> item +correctly in order to act meaningfully. + +</descrip> + +<sect2>Overview of module + +<p> +Provides standard Unix securetty checking. + +<sect2>Authentication component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> + +<tag><bf>Description:</bf></tag> + +Provides standard Unix securetty checking, which causes authentication +for root to fail unless <tt>PAM_TTY</tt> is set to a string listed in +the <tt>/etc/securetty</tt> file. For all other users, it succeeds. + +<tag><bf>Examples/suggested usage:</bf></tag> + +For canonical usage, should be listed as a <tt>required</tt> +authentication method before any <tt>sufficient</tt> authentication +methods. + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/modules/pam_time.sgml b/doc/modules/pam_time.sgml new file mode 100644 index 00000000..4104aad1 --- /dev/null +++ b/doc/modules/pam_time.sgml @@ -0,0 +1,166 @@ +<!-- + $Id$ + + This file was written by Andrew G. Morgan <morgan@parc.power.net> +--> + +<sect1>Time control + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +<tt/pam_time/ + +<tag><bf>Author:</bf></tag> +Andrew G. Morgan <tt><morgan@parc.power.net></tt> + +<tag><bf>Maintainer:</bf></tag> +Author + +<tag><bf>Management groups provided:</bf></tag> +account + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> + +<tag><bf>System dependencies:</bf></tag> +Requires a configuration file <tt>/etc/security/time.conf</tt> + +<tag><bf>Network aware:</bf></tag> +Through the <tt/PAM_TTY/ item only + +</descrip> + +<sect2>Overview of module + +<p> +Running a well regulated system occasionally involves restricting +access to certain services in a selective manner. This module offers +some time control for access to services offered by a system. Its +actions are determined with a configuration file. This module can be +configured to deny access to (individual) users based on their name, +the time of day, the day of week, the service they are applying for +and their terminal from which they are making their request. + +<sect2>Account component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> + +<tag><bf>Description:</bf></tag> + +This module bases its actions on the rules listed in its configuration +file: <tt>/etc/security/pam.conf</tt>. Each rule has the following +form, +<tscreen> +<em/services/<tt/;/<em/ttys/<tt/;/<em/users/<tt/;/<em/times/ +</tscreen> +In words, each rule occupies a line, terminated with a newline or the +beginning of a comment; a `<tt/#/'. It contains four fields separated +with semicolons, `<tt/;/'. The fields are as follows: + +<p> +<itemize> +<item><em/services/ - +a logic list of service names that are affected by this rule. + +<item><em/ttys/ - +a logic list of terminal names indicating those terminals covered by +the rule. + +<item><em/user/ - +a logic list of usernames to which this rule applies + +<p> +By a logic list we mean a sequence of tokens (associated with the +appropriate <tt/PAM_/ item), containing no more than one wildcard +character; `<tt/*/', and optionally prefixed with a negation operator; +`<tt/!/'. Such a sequence is concatenated with one of two logical +operators: <tt/&/ (logical AND) and <tt/|/ (logical OR). Two +examples are: <tt>!morgan&!root</tt>, indicating that this rule +does not apply to the user <tt>morgan</tt> nor to <tt>root</tt>; and +<tt>tty*&!ttyp*</tt>, which indicates that the rule applies only +to console terminals but not pseudoterminals. + +<item><em/times/ - a logic list of times at which this rule +applies. The format of each element is a day/time-range. The days are +specified by a sequence of two character entries. For example, +<tt/MoTuSa/, indicates Monday Tuesday and Saturday. Note that +repeated days are <em/unset/; <tt/MoTuMo/ indicates Tuesday, and +<tt/MoWk/ means all weekdays bar Monday. The two character +combinations accepted are, +<tscreen> +<verb> +Mo Tu We Th Fr Sa Su Wk Wd Al +</verb> +</tscreen> +The last two of these being <em/weekend/ days and <em/all 7 days/ of +the week respectively. + +<p> +The time range part is a pair of 24-hour times, <em/HHMM/, separated +by a hyphen -- indicating the start and finish time for the rule. If +the finsish time is smaller than the start time, it is assumed to +apply on the following day. For an example, <tt/Mo1800-0300/ indicates +that the permitted times are Monday night from 6pm to 3am the +following morning. + +</itemize> + +<p> +Note, that the given time restriction is only applied when the first +three fields are satisfied by a user's application for service. + +<p> +For convenience and readability a rule can be extended beyond a single +line with a `<tt>\</tt><em/newline/'. + +<tag><bf>Examples/suggested usage:</bf></tag> + +The use of this module is initiated with an entry in the +<bf/Linux-PAM/ configuration file of the following type: +<tscreen> +<verb> +# +# apply pam_time accounting to login requests +# +login account required pam_time.so +</verb> +</tscreen> +where, here we are applying the module to the <em/login/ application. + +<p> +Some examples of rules that can be placed in the +<tt>/etc/security/time.conf</tt> configuration file are the following: +<descrip> + +<tag><tt>login ; tty* & ; !ttyp* ; !root ; !Al0000-2400</tt></tag> +all users except for <tt/root/ are denied access to console-login at +all times. + +<tag><tt>games ; * ; !waster ; Wd0000-2400 | Wk1800-0800</tt></tag> +games (configured to use Linux-PAM) are only to be accessed out of +working hours. This rule does not apply to the user <tt/waster/. + +</descrip> + +<p> +Note, currently there is no daemon enforcing the end of a session. +This needs to be remedied. + +<p> +Poorly formatted rules are logged as errors using <tt/syslog(3)/. + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/modules/pam_unix.sgml b/doc/modules/pam_unix.sgml new file mode 100644 index 00000000..792362ed --- /dev/null +++ b/doc/modules/pam_unix.sgml @@ -0,0 +1,289 @@ +<!-- + This file was written by Andrew G. Morgan <morgan@linux.kernel.org> + + Converted from the pam_pwdb.sgml file for pam_unix by Ben Collins <bcollins@debian.org> +--> + +<sect1>The Unix Password module + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +pam_unix + +<tag><bf>Author:</bf></tag> + +<tag><bf>Maintainer:</bf></tag> +Authors. + +<tag><bf>Management groups provided:</bf></tag> +account; authentication; password; session + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> + +<tag><bf>System dependencies:</bf></tag> + +<tag><bf>Network aware:</bf></tag> + +</descrip> + +<sect2>Overview of module + +<p> +This is the standard Unix authentication module. It uses standard calls +from the system's libraries to retrieve and set account information as +well as authentication. Usually this is obtained from the /etc/passwd +and the /etc/shadow file aswell if shadow is enabled. + +<sect2>Account component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +<tt/debug/; <tt/audit/ + +<tag><bf>Description:</bf></tag> + +The <tt/debug/ argument makes the accounting functions of this module +<tt/syslog(3)/ more information on its actions. (Remaining arguments +supported by the other functions of this module are silently ignored, +but others are logged as errors through <tt/syslog(3)/). The <tt/audit/ +argument causes even more logging. + +Based on the following <tt/shadow/ elements: +<tt/expire/; +<tt/last_change/; +<tt/max_change/; +<tt/min_change/; +<tt/warn_change/, +this module performs the task of establishing the status of the user's +account and password. In the case of the latter, it may offer advice +to the user on changing their password or, through the +<tt/PAM_AUTHTOKEN_REQD/ return, delay giving service to the user until +they have established a new password. The entries listed above are +documented in the <em/GNU Libc/ info documents. Should the user's record +not contain one or more of these entries, the corresponding <em/shadow/ +check is not performed. + +<tag><bf>Examples/suggested usage:</bf></tag> + +In its accounting mode, this module can be inserted as follows: +<tscreen> +<verb> +# +# Ensure users account and password are still active +# +login account required pam_unix.so +</verb> +</tscreen> + +</descrip> + +<sect2>Authentication component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +<tt/debug/; +<tt/audit/; +<tt/use_first_pass/; +<tt/try_first_pass/; +<tt/nullok/; +<tt/nodelay/ + +<tag><bf>Description:</bf></tag> + +The <tt/debug/ argument makes the authentication functions of this +module <tt/syslog(3)/ more information on its actions. The <tt/audit/ +causes even more information to be logged. + +<p> +The default action of this module is to not permit the user access to +a service if their <em/official/ password is blank. The <tt/nullok/ +argument overrides this default. + +<p> +When given the argument <tt/try_first_pass/, before prompting the user +for their password, the module first tries the previous stacked +<tt/auth/-module's password in case that satisfies this module as +well. The argument <tt/use_first_pass/ forces the module to use such a +recalled password and will never prompt the user - if no password is +available or the password is not appropriate, the user will be denied +access. + +<p> +The argument, <tt>nodelay</tt>, can be used to discourage the +authentication component from requesting a delay should the +authentication as a whole fail. The default action is for the module +to request a delay-on-failure of the order of one second. + +<p> +Remaining arguments, supported by the other functions of this module, +are silently ignored. Other arguments are logged as errors through +<tt/syslog(3)/. + +<p> +A helper binary, <tt>unix_chkpwd</tt>, is provided to check the user's +password when it is stored in a read protected database. This binary +is very simple and will only check the password of the user invoking +it. It is called transparently on behalf of the user by the +authenticating component of this module. In this way it is possible +for applications like <em>xlock</em> to work without being setuid-root. + +<tag><bf>Examples/suggested usage:</bf></tag> + +The correct functionality of this module is dictated by having an +appropriate <tt>/etc/nsswitch.conf</tt> file, the user +databases specified there dictate the source of the authenticated +user's record. +<p> +In its authentication mode, this module can be inserted as follows: +<tscreen> +<verb> +# +# Authenticate the user +# +login auth required pam_unix.so +</verb> +</tscreen> + +</descrip> + +<sect2>Password component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +<tt/debug/; +<tt/audit/; +<tt/nullok/; +<tt/not_set_pass/; +<tt/use_authtok/; +<tt/try_first_pass/; +<tt/use_first_pass/; +<tt/md5/; +<tt/bigcrypt/; +<tt/shadow/; +<tt/nis/; +<tt/remember/ + +<tag><bf>Description:</bf></tag> + +This part of the <tt/pam_unix/ module performs the task of updating +the user's password. + +<p> +In the case of conventional unix databases (which store the password +encrypted) the <tt/md5/ argument is used to do the encryption with the +MD5 function as opposed to the <em/conventional/ <tt/crypt(3)/ call. +As an alternative to this, the <tt/bigcrypt/ argument can be used to +encrypt more than the first 8 characters of a password with DEC's +(Digital Equipment Cooperation) `C2' extension to the standard UNIX +<tt/crypt()/ algorithm. + +<p> +The <tt/nullok/ argument is used to permit the changing of a password +<em/from/ an empty one. Without this argument, empty passwords are +treated as account-locking ones. + +<p> +The argument <tt/use_first_pass/ is used to lock the choice of old and +new passwords to that dictated by the previously stacked <tt/password/ +module. The <tt/try_first_pass/ argument is used to avoid the user +having to re-enter an old password when <tt/pam_unix/ follows a module +that possibly shared the user's old password - if this old password is +not correct the user will be prompted for the correct one. The +argument <tt/use_authtok/ is used to <em/force/ this module to set the +new password to the one provided by the previously stacked +<tt/password/ module (this is used in an example of the stacking of +the <em/Cracklib/ module documented above). + +<p> +The <tt/not_set_pass/ argument is used to inform the module that it is +not to pay attention to/make available the old or new passwords from/to +other (stacked) password modules. + +<p> +The <tt/debug/ argument makes the password functions of this module +<tt/syslog(3)/ more information on its actions. Other arguments may be +logged as erroneous to <tt/syslog(3)/. The <tt/audit/ argument causes +even more information to be logged. + +<p> +With the <tt/nis/ argument, <tt/pam_unix/ will attempt to use NIS RPC +for setting new passwords. + +<p> +The <tt/remember/ argument takes one value. This is the number of most +recent passwords to save for each user. These are saved in +<tt>/etc/security/opasswd</tt> in order to force password change history +and keep the user from alternating between the same password too frequently. + +<tag><bf>Examples/suggested usage:</bf></tag> + +Standard usage: +<tscreen> +<verb> +# +# Change the users password +# +passwd password required pam_unix.so +</verb> +</tscreen> + +<p> +An example of the stacking of this module with respect to the +pluggable password checking module, <tt/pam_cracklib/: +<tscreen> +<verb> +# +# Change the users password +# +passwd password required pam_cracklib.so retry=3 minlen=6 difok=3 +passwd password required pam_unix.so use_authtok nullok md5 +</verb> +</tscreen> + +</descrip> + +<sect2>Session component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> + +<tag><bf>Description:</bf></tag> + +No arguments are recognized by this module component. Its action is +simply to log the username and the service-type to +<tt/syslog(3)/. Messages are logged at the beginning and end of the +user's session. + +<tag><bf>Examples/suggested usage:</bf></tag> + +The use of the session modules is straightforward: +<tscreen> +<verb> +# +# session opening and closing +# +login session required pam_unix.so +</verb> +</tscreen> + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/modules/pam_userdb.sgml b/doc/modules/pam_userdb.sgml new file mode 100644 index 00000000..bdbf80b8 --- /dev/null +++ b/doc/modules/pam_userdb.sgml @@ -0,0 +1,112 @@ +<!-- + This file was written by Cristian Gafton <gafton@redhat.com> +--> + +<sect1>The userdb module + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +<tt/pam_userdb/ + +<tag><bf>Author:</bf></tag> +Cristian Gafton <gafton@redhat.com> + +<tag><bf>Maintainer:</bf></tag> +Author. + +<tag><bf>Management groups provided:</bf></tag> +authentication + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> + +<tag><bf>System dependencies:</bf></tag> +Requires Berkeley DB. + +<tag><bf>Network aware:</bf></tag> + +</descrip> + +<sect2>Overview of module + +<p> +Look up users in a .db database and verify their password against +what is contained in that database. + +<sect2>Authentication component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +<tt/debug/; +<tt/icase/; +<tt/dump/; +<tt/db=XXXX/; + +<tag><bf>Description:</bf></tag> + +This module is used to verify a username/password pair against values stored in +a Berkeley DB database. The database is indexed by the username, and the data +fields corresponding to the username keys are the passwords, in unencrypted form, +so caution must be exercised over the access rights to the DB database itself.. + +The module will read the password from the user using the conversation mechanism. If +you are using this module on top of another authetication module (like <tt/pam_pwdb/;) +then you should tell that module to read the entered password from the PAM_AUTHTOK field, which is set by this module. + +<p> +The action of the module may be modified from this default by one or +more of the following flags in the <tt>/etc/pam.d/<service></tt> file. +<itemize> +<item> +<tt/debug/ - +Supply more debugging information to <tt/syslog(3)/. + +<item> +<tt/icase/ - +Perform the password comparisons case insensitive. + +<item> +<tt/dump/ - +dump all the entries in the database to the log (eek, +don't do this by default!) + +<item> +<tt/db=XXXX/ - +use the database found on pathname XXXX. Note that Berkeley DB usually adds the +needed filename extension for you, so you should use something like <tt>/etc/foodata</tt> +instead of <tt>/etc/foodata.db</tt>. + +</itemize> + +<tag><bf>Examples/suggested usage:</bf></tag> + +This is a normal ftp configuration file (usually placed as <tt>/etc/pam.d/ftp</tt> +on most systems) that will accept for login users whose username/password pairs are +provided in the <tt>/tmp/dbtest.db</tt> file: + +<tscreen> +<verb> +#%PAM-1.0 +auth required pam_listfile.so item=user sense=deny file=/etc/ftpusers onerr=succeed +auth sufficient pam_userdb.so icase db=/tmp/dbtest +auth required pam_pwdb.so shadow nullok try_first_pass +auth required pam_shells.so +account required pam_pwdb.so +session required pam_pwdb.so +</verb> +</tscreen> + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/modules/pam_warn.sgml b/doc/modules/pam_warn.sgml new file mode 100644 index 00000000..2ca4cc82 --- /dev/null +++ b/doc/modules/pam_warn.sgml @@ -0,0 +1,67 @@ +<!-- + $Id$ + + This file was written by Andrew G. Morgan <morgan@parc.power.net> +--> + +<sect1>Warning logger module + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +<tt/pam_warn/ + +<tag><bf>Author:</bf></tag> +Andrew G. Morgan <morgan@parc.power.net> + +<tag><bf>Maintainer:</bf></tag> +Author. + +<tag><bf>Management groups provided:</bf></tag> +authentication; password + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> + +<tag><bf>System dependencies:</bf></tag> + +<tag><bf>Network aware:</bf></tag> +logs information about the remote user and host (if pam-items are known) + +</descrip> + +<sect2>Overview of module + +<p> +This module is principally for logging information about a +proposed authentication or application to update a password. + +<sect2>Authentication+Password component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> + +<tag><bf>Description:</bf></tag> + +Log the service, terminal, user, remote user and remote host to +<tt/syslog(3)/. The items are not probed for, but instead obtained +from the standard pam-items. + +<tag><bf>Examples/suggested usage:</bf></tag> + +an example is provided in the configuration file section <ref +id="configuration" name="above">. + +</descrip> + +<!-- +End of sgml insert for this module. +--> diff --git a/doc/modules/pam_wheel.sgml b/doc/modules/pam_wheel.sgml new file mode 100644 index 00000000..1eb62743 --- /dev/null +++ b/doc/modules/pam_wheel.sgml @@ -0,0 +1,125 @@ +<!-- + $Id$ + + This file was written by Andrew G. Morgan <morgan@parc.power.net> + from notes provided by Cristian Gafton. +--> + +<sect1>The wheel module + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> +<tt/pam_wheel/ + +<tag><bf>Author:</bf></tag> +Cristian Gafton <gafton@redhat.com> + +<tag><bf>Maintainer:</bf></tag> +Author. + +<tag><bf>Management groups provided:</bf></tag> +authentication + +<tag><bf>Cryptographically sensitive:</bf></tag> + +<tag><bf>Security rating:</bf></tag> + +<tag><bf>Clean code base:</bf></tag> + +<tag><bf>System dependencies:</bf></tag> +Requires libpwdb. + +<tag><bf>Network aware:</bf></tag> + +</descrip> + +<sect2>Overview of module + +<p> +Only permit root access to members of the wheel (<tt/gid=0/) group. + +<sect2>Authentication component + +<p> +<descrip> + +<tag><bf>Recognized arguments:</bf></tag> +<tt/debug/; +<tt/use_uid/; +<tt/trust/; +<tt/deny/; +<tt/group=XXXX/ + +<tag><bf>Description:</bf></tag> + +This module is used to enforce the so-called <em/wheel/ group. By +default, it permits root access to the system if the applicant user is +a member of the <tt/wheel/ group (first, the module checks for the +existence of a '<tt/wheel/' group. Otherwise the module defines the +group with group-id <tt/0/ to be the <em/wheel/ group). + +<p> +The action of the module may be modified from this default by one or +more of the following flags in the <tt>/etc/pam.conf</tt> file. +<itemize> +<item> +<tt/debug/ - +Supply more debugging information to <tt/syslog(3)/. + +<item> +<tt/use_uid/ - +This option modifies the behavior of the module by using the current +<tt/uid/ of the process and not the <tt/getlogin(3)/ name of the user. +This option is useful for being able to jump from one account to +another, for example with 'su'. + +<item> +<tt/trust/ - +This option instructs the module to return <tt/PAM_SUCCESS/ should it +find the user applying for root privilege is a member of the wheel +group. The default action is to return <tt/PAM_IGNORE/ in this +situation. By using the <tt/trust/ option it is possible to arrange +for <tt/wheel/-group members to become root without typing a +password. <bf/USE WITH CARE/. + +<item> +<tt/deny/ - +This is used to reverse the logic of the module's behavior. +If the user is trying to get <tt/uid=0/ access and is a member of the wheel +group, deny access (for the wheel group, this is perhaps nonsense!): +it is intended for use in conjunction with the <tt/group=/ argument... + +<item> +<tt/group=XXXX/ - +Instead of checking the <tt/gid=0/ group, use the user's <tt/XXXX/ +group membership for the authentication. Here, <tt/XXXX/ is the name +of the group and <bf/not/ its numeric identifier. + +</itemize> + +<tag><bf>Examples/suggested usage:</bf></tag> + +To restrict access to superuser status to the members of the +<tt/wheel/ group, use the following entries in your configuration +file: +<tscreen> +<verb> +# +# root gains access by default (rootok), only wheel members can +# become root (wheel) but Unix authenticate non-root applicants. +# +su auth sufficient pam_rootok.so +su auth required pam_wheel.so +su auth required pam_unix_auth.so +</verb> +</tscreen> + +</descrip> + +<!-- +End of sgml insert for this module. +--> |