diff options
Diffstat (limited to 'Linux-PAM/doc/modules/pam_pwdb.sgml')
| -rw-r--r-- | Linux-PAM/doc/modules/pam_pwdb.sgml | 249 |
1 files changed, 249 insertions, 0 deletions
diff --git a/Linux-PAM/doc/modules/pam_pwdb.sgml b/Linux-PAM/doc/modules/pam_pwdb.sgml new file mode 100644 index 00000000..df0cb329 --- /dev/null +++ b/Linux-PAM/doc/modules/pam_pwdb.sgml @@ -0,0 +1,249 @@ +<!-- + $Id: pam_pwdb.sgml,v 1.1.1.2 2002/09/15 20:08:32 hartmans Exp $ + + This file was written by Andrew G. Morgan <morgan@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@kernel.org> + +<tag><bf>Maintainer:</bf></tag> +Red Hat. + +<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>libpwdb</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. +--> |