4 This file was written by Andrew G. Morgan <morgan@linux.kernel.org>
7 <sect1>The Password-Database module
14 <tag><bf>Module Name:</bf></tag>
17 <tag><bf>Author:</bf></tag>
18 Cristian Gafton <gafton@redhat.com> <newline>
19 and Andrew G. Morgan <morgan@linux.kernel.org>
21 <tag><bf>Maintainer:</bf></tag>
24 <tag><bf>Management groups provided:</bf></tag>
25 account; authentication; password; session
27 <tag><bf>Cryptographically sensitive:</bf></tag>
29 <tag><bf>Security rating:</bf></tag>
31 <tag><bf>Clean code base:</bf></tag>
33 <tag><bf>System dependencies:</bf></tag>
34 Requires properly configured <tt/libpwdb/
36 <tag><bf>Network aware:</bf></tag>
40 <sect2>Overview of module
43 This module is a pluggable replacement for the <tt/pam_unix_../
44 modules. It uses the generic interface of the <em/Password Database/
47 url="http://linux.kernel.org/morgan/libpwdb/index.html"
48 name="http://linux.kernel.org/morgan/libpwdb/index.html"></tt>.
50 <sect2>Account component
55 <tag><bf>Recognized arguments:</bf></tag>
58 <tag><bf>Description:</bf></tag>
60 The <tt/debug/ argument makes the accounting functions of this module
61 <tt/syslog(3)/ more information on its actions. (Remaining arguments
62 supported by the other functions of this module are silently ignored,
63 but others are logged as errors through <tt/syslog(3)/).
65 Based on the following <tt/pwdb_element/s:
71 this module performs the task of establishing the status of the user's
72 account and password. In the case of the latter, it may offer advice
73 to the user on changing their password or, through the
74 <tt/PAM_AUTHTOKEN_REQD/ return, delay giving service to the user until
75 they have established a new password. The entries listed above are
76 documented in the <em/Password Database Library Guide/ (see pointer
77 above). Should the user's record not contain one or more of these
78 entries, the corresponding <em/shadow/ check is not performed.
80 <tag><bf>Examples/suggested usage:</bf></tag>
82 In its accounting mode, this module can be inserted as follows:
86 # Ensure users account and password are still active
88 login account required pam_pwdb.so
94 <sect2>Authentication component
99 <tag><bf>Recognized arguments:</bf></tag>
107 <tag><bf>Description:</bf></tag>
109 The <tt/debug/ argument makes the authentication functions of this
110 module <tt/syslog(3)/ more information on its actions.
113 The default action of this module is to not permit the user access to
114 a service if their <em/official/ password is blank. The <tt/nullok/
115 argument overrides this default.
118 When given the argument <tt/try_first_pass/, before prompting the user
119 for their password, the module first tries the previous stacked
120 <tt/auth/-module's password in case that satisfies this module as
121 well. The argument <tt/use_first_pass/ forces the module to use such a
122 recalled password and will never prompt the user - if no password is
123 available or the password is not appropriate, the user will be denied
127 The argument, <tt>nodelay</tt>, can be used to discourage the
128 authentication component from requesting a delay should the
129 authentication as a whole fail. The default action is for the module
130 to request a delay-on-failure of the order of one second.
133 Remaining arguments, supported by the other functions of this module,
134 are silently ignored. Other arguments are logged as errors through
138 A helper binary, <tt>pwdb_chkpwd</tt>, is provided to check the user's
139 password when it is stored in a read protected database. This binary
140 is very simple and will only check the password of the user invoking
141 it. It is called transparently on behalf of the user by the
142 authenticating component of this module. In this way it is possible
143 for applications like <em>xlock</em> to work without being setuid-root.
146 The <tt>likeauth</tt> argument makes the module return the same value
147 when called as a credential setting module and an authentication
148 module. This will help libpam take a sane path through the auth
149 component of your configuration file.
151 <tag><bf>Examples/suggested usage:</bf></tag>
153 The correct functionality of this module is dictated by having an
154 appropriate <tt>/etc/pwdb.conf</tt> file, the user
155 databases specified there dictate the source of the authenticated
160 <sect2>Password component
165 <tag><bf>Recognized arguments:</bf></tag>
166 <tt/debug/; <tt/nullok/; <tt/not_set_pass/; <tt/use_authtok/;
167 <tt/try_first_pass/; <tt/use_first_pass/; <tt/md5/; <tt/bigcrypt/;
168 <tt/shadow/; <tt/radius/; <tt/unix/
170 <tag><bf>Description:</bf></tag>
172 This part of the <tt/pam_pwdb/ module performs the task of updating
173 the user's password. Thanks to the flexibility of <tt/libpwdb/ this
174 module is able to move the user's password from one database to
175 another, perhaps securing the user's database entry in a dynamic
176 manner (<em/this is very ALPHA code at the moment!/) - this is the
177 purpose of the <tt/shadow/, <tt/radius/ and <tt/unix/ arguments.
180 In the case of conventional unix databases (which store the password
181 encrypted) the <tt/md5/ argument is used to do the encryption with the
182 MD5 function as opposed to the <em/conventional/ <tt/crypt(3)/ call.
183 As an alternative to this, the <tt/bigcrypt/ argument can be used to
184 encrypt more than the first 8 characters of a password with DEC's
185 (Digital Equipment Cooperation) `C2' extension to the standard UNIX
186 <tt/crypt()/ algorithm.
189 The <tt/nullok/ module is used to permit the changing of a password
190 <em/from/ an empty one. Without this argument, empty passwords are
191 treated as account-locking ones.
194 The argument <tt/use_first_pass/ is used to lock the choice of old and
195 new passwords to that dictated by the previously stacked <tt/password/
196 module. The <tt/try_first_pass/ argument is used to avoid the user
197 having to re-enter an old password when <tt/pam_pwdb/ follows a module
198 that possibly shared the user's old password - if this old password is
199 not correct the user will be prompted for the correct one. The
200 argument <tt/use_authtok/ is used to <em/force/ this module to set the
201 new password to the one provided by the previously stacked
202 <tt/password/ module (this is used in an example of the stacking of
203 the <em/Cracklib/ module documented above).
206 The <tt/not_set_pass/ argument is used to inform the module that it is
207 not to pay attention to/make available the old or new passwords from/to
208 other (stacked) password modules.
211 The <tt/debug/ argument makes the password functions of this module
212 <tt/syslog(3)/ more information on its actions. Other arguments may be
213 logged as erroneous to <tt/syslog(3)/.
215 <tag><bf>Examples/suggested usage:</bf></tag>
217 An example of the stacking of this module with respect to the
218 pluggable password checking module, <tt/pam_cracklib/, is given in
219 that modules section above.
222 <sect2>Session component
227 <tag><bf>Recognized arguments:</bf></tag>
229 <tag><bf>Description:</bf></tag>
231 No arguments are recognized by this module component. Its action is
232 simply to log the username and the service-type to
233 <tt/syslog(3)/. Messages are logged at the beginning and end of the
236 <tag><bf>Examples/suggested usage:</bf></tag>
238 The use of the session modules is straightforward:
242 # pwdb - unix like session opening and closing
244 login session required pam_pwdb.so
251 End of sgml insert for this module.