71cb07e32863b4d1aee4f20052c276b5c9be8132
[dragonfly.git] / contrib / libpam / doc / modules / pam_unix.sgml
1 <!--
2    This file was written by Andrew G. Morgan <morgan@linux.kernel.org>
3
4    Converted from the pam_pwdb.sgml file for pam_unix by Ben Collins <bcollins@debian.org>
5 -->
6
7 <sect1>The Unix Password module
8
9 <sect2>Synopsis
10
11 <p>
12 <descrip>
13
14 <tag><bf>Module Name:</bf></tag>
15 pam_unix
16
17 <tag><bf>Author:</bf></tag>
18
19 <tag><bf>Maintainer:</bf></tag>
20
21 <tag><bf>Management groups provided:</bf></tag>
22 account; authentication; password; session
23
24 <tag><bf>Cryptographically sensitive:</bf></tag>
25         
26 <tag><bf>Security rating:</bf></tag>
27
28 <tag><bf>Clean code base:</bf></tag>
29
30 <tag><bf>System dependencies:</bf></tag>
31
32 <tag><bf>Network aware:</bf></tag>
33
34 </descrip>
35
36 <sect2>Overview of module
37
38 <p>
39 This is the standard Unix authentication module. It uses standard calls
40 from the system's libraries to retrieve and set account information as
41 well as authentication. Usually this is obtained from the /etc/passwd
42 and the /etc/shadow file as well if shadow is enabled.
43
44 <sect2>Account component
45
46 <p>
47 <descrip>
48
49 <tag><bf>Recognized arguments:</bf></tag>
50 <tt/debug/; <tt/audit/
51
52 <tag><bf>Description:</bf></tag>
53
54 The <tt/debug/ argument makes the accounting functions of this module
55 <tt/syslog(3)/ more information on its actions. (Remaining arguments
56 supported by the other functions of this module are silently ignored,
57 but others are logged as errors through <tt/syslog(3)/). The <tt/audit/
58 argument causes even more logging.
59
60 Based on the following <tt/shadow/ elements:
61 <tt/expire/;
62 <tt/last_change/;
63 <tt/max_change/;
64 <tt/min_change/;
65 <tt/warn_change/,
66 this module performs the task of establishing the status of the user's
67 account and password. In the case of the latter, it may offer advice
68 to the user on changing their password or, through the
69 <tt/PAM_AUTHTOKEN_REQD/ return, delay giving service to the user until
70 they have established a new password. The entries listed above are
71 documented in the <em/GNU Libc/ info documents. Should the user's record
72 not contain one or more of these entries, the corresponding <em/shadow/
73 check is not performed.
74
75 <tag><bf>Examples/suggested usage:</bf></tag>
76
77 In its accounting mode, this module can be inserted as follows:
78 <tscreen>
79 <verb>
80 #
81 # Ensure users account and password are still active
82 #
83 login   account  required       pam_unix.so
84 </verb>
85 </tscreen>
86
87 </descrip>
88
89 <sect2>Authentication component
90
91 <p>
92 <descrip>
93
94 <tag><bf>Recognized arguments:</bf></tag>
95 <tt/debug/;
96 <tt/audit/;
97 <tt/use_first_pass/;
98 <tt/try_first_pass/;
99 <tt/nullok/;
100 <tt/nodelay/
101
102 <tag><bf>Description:</bf></tag>
103
104 The <tt/debug/ argument makes the authentication functions of this
105 module <tt/syslog(3)/ more information on its actions. The <tt/audit/
106 causes even more information to be logged.
107
108 <p>
109 The default action of this module is to not permit the user access to
110 a service if their <em/official/ password is blank. The <tt/nullok/
111 argument overrides this default.
112
113 <p>
114 When given the argument <tt/try_first_pass/, before prompting the user
115 for their password, the module first tries the previous stacked
116 <tt/auth/-module's password in case that satisfies this module as
117 well. The argument <tt/use_first_pass/ forces the module to use such a
118 recalled password and will never prompt the user - if no password is
119 available or the password is not appropriate, the user will be denied
120 access.
121
122 <p>
123 The argument, <tt>nodelay</tt>, can be used to discourage the
124 authentication component from requesting a delay should the
125 authentication as a whole fail.  The default action is for the module
126 to request a delay-on-failure of the order of one second.
127
128 <p>
129 Remaining arguments, supported by the other functions of this module,
130 are silently ignored. Other arguments are logged as errors through
131 <tt/syslog(3)/.
132
133 <p>
134 A helper binary, <tt>unix_chkpwd</tt>, is provided to check the user's
135 password when it is stored in a read protected database.  This binary
136 is very simple and will only check the password of the user invoking
137 it.  It is called transparently on behalf of the user by the
138 authenticating component of this module.  In this way it is possible
139 for applications like <em>xlock</em> to work without being setuid-root.
140
141 <tag><bf>Examples/suggested usage:</bf></tag>
142
143 The correct functionality of this module is dictated by having an
144 appropriate <tt>/etc/nsswitch.conf</tt> file, the user
145 databases specified there dictate the source of the authenticated
146 user's record.
147 <p>
148 In its authentication mode, this module can be inserted as follows:
149 <tscreen>
150 <verb>
151 #
152 # Authenticate the user
153 #
154 login   auth  required       pam_unix.so
155 </verb>
156 </tscreen>
157
158 </descrip>
159
160 <sect2>Password component
161
162 <p>
163 <descrip>
164
165 <tag><bf>Recognized arguments:</bf></tag>
166 <tt/debug/;
167 <tt/audit/;
168 <tt/nullok/;
169 <tt/not_set_pass/;
170 <tt/use_authtok/;
171 <tt/try_first_pass/;
172 <tt/use_first_pass/;
173 <tt/md5/;
174 <tt/bigcrypt/;
175 <tt/shadow/;
176 <tt/nis/;
177 <tt/remember/
178
179 <tag><bf>Description:</bf></tag>
180
181 This part of the <tt/pam_unix/ module performs the task of updating
182 the user's password.
183
184 <p>
185 In the case of conventional unix databases (which store the password
186 encrypted) the <tt/md5/ argument is used to do the encryption with the
187 MD5 function as opposed to the <em/conventional/ <tt/crypt(3)/ call.
188 As an alternative to this, the <tt/bigcrypt/ argument can be used to
189 encrypt more than the first 8 characters of a password with DEC's
190 (Digital Equipment Cooperation) `C2' extension to the standard UNIX
191 <tt/crypt()/ algorithm.
192
193 <p>
194 The <tt/nullok/ argument is used to permit the changing of a password
195 <em/from/ an empty one. Without this argument, empty passwords are
196 treated as account-locking ones.
197
198 <p>
199 The argument <tt/use_first_pass/ is used to lock the choice of old and
200 new passwords to that dictated by the previously stacked <tt/password/
201 module.  The <tt/try_first_pass/ argument is used to avoid the user
202 having to re-enter an old password when <tt/pam_unix/ follows a module
203 that possibly shared the user's old password - if this old password is
204 not correct the user will be prompted for the correct one.  The
205 argument <tt/use_authtok/ is used to <em/force/ this module to set the
206 new password to the one provided by the previously stacked
207 <tt/password/ module (this is used in an example of the stacking of
208 the <em/Cracklib/ module documented above).
209
210 <p>
211 The <tt/not_set_pass/ argument is used to inform the module that it is
212 not to pay attention to/make available the old or new passwords from/to
213 other (stacked) password modules.
214
215 <p>
216 The <tt/debug/ argument makes the password functions of this module
217 <tt/syslog(3)/ more information on its actions. Other arguments may be
218 logged as erroneous to <tt/syslog(3)/. The <tt/audit/ argument causes
219 even more information to be logged.
220
221 <p>
222 With the <tt/nis/ argument, <tt/pam_unix/ will attempt to use NIS RPC
223 for setting new passwords.
224
225 <p>
226 The <tt/remember/ argument takes one value. This is the number of most
227 recent passwords to save for each user. These are saved in
228 <tt>/etc/security/opasswd</tt> in order to force password change history
229 and keep the user from alternating between the same password too frequently.
230
231 <tag><bf>Examples/suggested usage:</bf></tag>
232
233 Standard usage:
234 <tscreen>
235 <verb>
236 #
237 # Change the users password
238 #
239 passwd   password   required   pam_unix.so
240 </verb>
241 </tscreen>
242
243 <p>
244 An example of the stacking of this module with respect to the
245 pluggable password checking module, <tt/pam_cracklib/:
246 <tscreen>
247 <verb>
248 #
249 # Change the users password
250 #
251 passwd   password   required   pam_cracklib.so retry=3 minlen=6 difok=3
252 passwd   password   required   pam_unix.so use_authtok nullok md5
253 </verb>
254 </tscreen>
255
256 </descrip>
257
258 <sect2>Session component
259
260 <p>
261 <descrip>
262
263 <tag><bf>Recognized arguments:</bf></tag>
264
265 <tag><bf>Description:</bf></tag>
266
267 No arguments are recognized by this module component. Its action is
268 simply to log the username and the service-type to
269 <tt/syslog(3)/. Messages are logged at the beginning and end of the
270 user's session.
271
272 <tag><bf>Examples/suggested usage:</bf></tag>
273
274 The use of the session modules is straightforward:
275 <tscreen>
276 <verb>
277 #
278 # session opening and closing
279 #
280 login   session  required       pam_unix.so
281 </verb>
282 </tscreen>
283
284 </descrip>
285
286 <!--
287 End of sgml insert for this module.
288 -->