Commit | Line | Data |
---|---|---|
805e021f CE |
1 | =head1 NAME |
2 | ||
3 | kas_setfields - Sets fields in an Authentication Database entry | |
4 | ||
5 | =head1 SYNOPSIS | |
6 | ||
7 | =for html | |
8 | <div class="synopsis"> | |
9 | ||
10 | B<kas setfields> S<<< B<-name> <I<name of user>> >>> | |
11 | S<<< [B<-flags> <I<hex flag value or flag name expression>>] >>> | |
12 | S<<< [B<-expiration> <I<date of account expiration>>] >>> | |
13 | S<<< [B<-lifetime> <I<maximum ticket lifetime>>] >>> | |
14 | S<<< [B<-pwexpires> <I<number days password is valid ([0..254])>>] >>> | |
15 | S<<< [B<-reuse> <I<permit password reuse (yes/no)>>] >>> | |
16 | S<<< [B<-attempts> <I<maximum successive failed login tries ([0..254])>>] >>> | |
17 | S<<< [B<-locktime> <I<failure penalty [hh:mm or minutes]>>] >>> | |
18 | S<<< [B<-admin_username> <I<admin principal to use for authentication>>] >>> | |
19 | S<<< [B<-password_for_admin> <I<admin password>>] >>> S<<< [B<-cell> <I<cell name>>] >>> | |
20 | S<<< [B<-servers> <I<explicit list of authentication servers>>+] >>> | |
21 | [B<-noauth>] [B<-help>] | |
22 | ||
23 | B<kas setf> S<<< B<-na> <I<name of user>> >>> | |
24 | S<<< [B<-f> <I<hex flag value or flag name expression>>] >>> | |
25 | S<<< [B<-e> <I<date of account expiration>>] >>> | |
26 | S<<< [B<-li> <I<maximum ticket lifetime>>] >>> | |
27 | S<<< [B<-pw> <I<number days password is valid ([0..254])>>] >>> | |
28 | S<<< [B<-r> <I<permit password reuse (yes/no)>>] >>> | |
29 | S<<< [B<-at> <I<maximum successive failed login tries ([0..254])>>] >>> | |
30 | S<<< [B<-lo> <I<failure penalty [hh:mm or minutes]>>] >>> | |
31 | S<<< [B<-ad> <I<admin principal to use for authentication>>] >>> | |
32 | S<<< [B<-pa> <I<admin password>>] >>> S<<< [B<-c> <I<cell name>>] >>> | |
33 | S<<< [B<-s> <I<explicit list of authentication servers>>+] >>> [B<-no>] [B<-h>] | |
34 | ||
35 | B<kas sf> S<<< B<-na> <I<name of user>> >>> | |
36 | S<<< [B<-f> <I<hex flag value or flag name expression>>] >>> | |
37 | S<<< [B<-e> <I<date of account expiration>>] >>> | |
38 | S<<< [B<-li> <I<maximum ticket lifetime>>] >>> | |
39 | S<<< [B<-pw> <I<number days password is valid ([0..254])>>] >>> | |
40 | S<<< [B<-r> <I<permit password reuse (yes/no)>>] >>> | |
41 | S<<< [B<-at> <I<maximum successive failed login tries ([0..254])>>] >>> | |
42 | S<<< [B<-lo> <I<failure penalty [hh:mm or minutes]>>] >>> | |
43 | S<<< [B<-ad> <I<admin principal to use for authentication>>] >>> | |
44 | S<<< [B<-pa> <I<admin password>>] >>> S<<< [B<-c> <I<cell name>>] >>> | |
45 | S<<< [B<-s> <I<explicit list of authentication servers>>+] >>> [B<-no>] [B<-h>] | |
46 | ||
47 | =for html | |
48 | </div> | |
49 | ||
50 | =head1 DESCRIPTION | |
51 | ||
52 | The B<kas setfields> command changes the Authentication Database entry for | |
53 | the user named by the B<-name> argument in the manner specified by the | |
54 | various optional arguments, which can occur singly or in combination: | |
55 | ||
56 | =over 4 | |
57 | ||
58 | =item * | |
59 | ||
60 | To set the flags that determine whether the user has administrative | |
61 | privileges to the Authentication Server, can obtain a ticket, can change | |
62 | his or her password, and so on, include the B<-flags> argument. | |
63 | ||
64 | =item * | |
65 | ||
66 | To set when the Authentication Database entry expires, include the | |
67 | B<-expiration> argument. | |
68 | ||
69 | =item * | |
70 | ||
71 | To set the maximum ticket lifetime associated with the entry, include the | |
72 | B<-lifetime> argument. L<klog(1)> explains how this value interacts with | |
73 | others to determine the actual lifetime of a token. | |
74 | ||
75 | =item * | |
76 | ||
77 | To set when the user's password expires, include the B<-pwexpires> | |
78 | argument. | |
79 | ||
80 | =item * | |
81 | ||
82 | To set whether the user can reuse any of the previous twenty passwords | |
83 | when creating a new one, include the B<-reuse> argument. | |
84 | ||
85 | =item * | |
86 | ||
87 | To set the maximum number of times the user can provide an incorrect | |
88 | password before the Authentication Server refuses to accept any more | |
89 | attempts (locks the issuer out), include the B<-attempts> argument. After | |
90 | the sixth failed authentication attempt, the Authentication Server logs a | |
91 | message in the UNIX system log file (the F<syslog> file or equivalent, for | |
92 | which the standard location varies depending on the operating system). | |
93 | ||
94 | =item * | |
95 | ||
96 | To set how long the Authentication Server refuses to process | |
97 | authentication attempts for a locked-out user, set the B<-locktime> | |
98 | argument. | |
99 | ||
100 | =back | |
101 | ||
102 | The B<kas examine> command displays the settings made with this command. | |
103 | ||
104 | =head1 CAUTIONS | |
105 | ||
106 | The password lifetime set with the B<-pwexpires> argument begins at the | |
107 | time the user's password was last changed, rather than when this command | |
108 | is issued. It can therefore be retroactive. If, for example, a user | |
109 | changed her password 100 days ago and the password lifetime is set to 100 | |
110 | days or less, the password effectively expires immediately. To avoid | |
111 | retroactive expiration, instruct the user to change the password just | |
112 | before setting a password lifetime. | |
113 | ||
114 | Administrators whose authentication accounts have the C<ADMIN> flag enjoy | |
115 | complete access to the sensitive information in the Authentication | |
116 | Database. To prevent access by unauthorized users, use the B<-attempts> | |
117 | argument to impose a fairly strict limit on the number of times that a | |
118 | user obtaining administrative tokens can provide an incorrect | |
119 | password. Note, however, that there must be more than one account in the | |
120 | cell with the C<ADMIN> flag. The B<kas unlock> command requires the | |
121 | C<ADMIN> privilege, so it is important that the locked-out administrator | |
122 | (or a colleague) can access another C<ADMIN>-privileged account to unlock | |
123 | the current account. | |
124 | ||
125 | In certain circumstances, the mechanism used to enforce the number of | |
126 | failed authentication attempts can cause a lockout even though the number | |
127 | of failed attempts is less than the limit set by the B<-attempts> | |
128 | argument. Client-side authentication programs such as B<klog> and an | |
129 | AFS-modified login utility normally choose an Authentication Server at | |
130 | random for each authentication attempt, and in case of a failure are | |
131 | likely to choose a different Authentication Server for the next | |
132 | attempt. The Authentication Servers running on the various database server | |
133 | machines do not communicate with each other about how many times a user | |
134 | has failed to provide the correct password to them. Instead, each | |
135 | Authentication Server maintains its own separate copy of the auxiliary | |
136 | database file F<kaserverauxdb> (located in the F</usr/afs/local> directory | |
137 | by default), which records the number of consecutive authentication | |
138 | failures for each user account and the time of the most recent | |
139 | failure. This implementation means that on average each Authentication | |
140 | Server knows about only a fraction of the total number of failed | |
141 | attempts. The only way to avoid allowing more than the number of attempts | |
142 | set by the B<-attempts> argument is to have each Authentication Server | |
143 | allow only some fraction of the total. More specifically, if the limit on | |
144 | failed attempts is I<f>, and the number of Authentication Servers is I<S>, | |
145 | then each Authentication Server can only permit a number of attempts equal | |
146 | to I<f> divided by I<S> (the Ubik synchronization site for the | |
147 | Authentication Server tracks any remainder, I<f> mod I<S>). | |
148 | ||
149 | Normally, this implementation does not reduce the number of allowed | |
150 | attempts to less than the configured limit (I<f>). If one Authentication | |
151 | Server refuses an attempt, the client contacts another instance of the | |
152 | server, continuing until either it successfully authenticates or has | |
153 | contacted all of the servers. However, if one or more of the | |
154 | Authentication Server processes is unavailable, the limit is effectively | |
155 | reduced by a percentage equal to the quantity I<U> divided by I<S>, where | |
156 | I<U> is the number of unavailable servers and I<S> is the number normally | |
157 | available. | |
158 | ||
159 | To avoid the undesirable consequences of setting a limit on failed | |
160 | authentication attempts, note the following recommendations: | |
161 | ||
162 | =over 4 | |
163 | ||
164 | =item * | |
165 | ||
166 | Do not set the B<-attempts> argument (the limit on failed authentication | |
167 | attempts) too low. A limit of nine failed attempts is recommended for | |
168 | regular user accounts, to allow three failed attempts per Authentication | |
169 | Server in a cell with three database server machines. | |
170 | ||
171 | =item * | |
172 | ||
173 | Set fairly short lockout times when including the B<-locktime> | |
174 | argument. Although guessing passwords is a common method of attack, it is | |
175 | not a very sophisticated one. Setting a lockout time can help discourage | |
176 | attackers, but excessively long times are likely to be more of a burden to | |
177 | authorized users than to potential attackers. A lockout time of 25 minutes | |
178 | is recommended for regular user accounts. | |
179 | ||
180 | =item * | |
181 | ||
182 | Do not assign an infinite lockout time on an account (by setting the | |
183 | B<-locktime> argument to C<0> [zero]) unless there is a highly compelling | |
184 | reason. Such accounts almost inevitably become locked at some point, | |
185 | because each Authentication Server never resets the account's failure | |
186 | counter in its copy of the F<kaauxdb> file (in contrast, when the lockout | |
187 | time is not infinite, the counter resets after the specified amount of | |
188 | time has passed since the last failed attempt to that Authentication | |
189 | Server). Furthermore, the only way to unlock an account with an infinite | |
190 | lockout time is for an administrator to issue the B<kas unlock> | |
191 | command. It is especially dangerous to set an infinite lockout time on an | |
192 | administrative account; if all administrative accounts become locked, the | |
193 | only way to unlock them is to shut down all instances of the | |
194 | Authentication Server and remove the F<kaauxdb> file on each. | |
195 | ||
196 | =back | |
197 | ||
198 | =head1 OPTIONS | |
199 | ||
200 | =over 4 | |
201 | ||
202 | =item B<-name> <I<name of user>> | |
203 | ||
204 | Names the Authentication Database account for which to change settings. | |
205 | ||
206 | =item B<-flags> <I<hex flag or flag name expression>> | |
207 | ||
208 | Sets one or more of four toggling flags, adding them to any flags | |
209 | currently set. Either specify one or more of the following strings, or | |
210 | specify a hexadecimal number that combines the indicated values. To return | |
211 | all four flags to their defaults, provide a value of C<0> (zero). To set | |
212 | more than one flag at once using the strings, connect them with plus signs | |
213 | (example: C<NOTGS+ADMIN+CPW>). To remove all the current flag settings | |
214 | before setting new ones, precede the list with an equal sign (example: | |
215 | C<=NOTGS+ADMIN+CPW>). | |
216 | ||
217 | =over 4 | |
218 | ||
219 | =item ADMIN | |
220 | ||
221 | The user is allowed to issue privileged kas commands (hexadecimal | |
222 | equivalent is C<0x004>, default is C<NOADMIN>). | |
223 | ||
224 | =item NOTGS | |
225 | ||
226 | The Authentication Server's Ticket Granting Service (TGS) refuses to issue | |
227 | tickets to the user (hexadecimal equivalent is C<0x008>, default is | |
228 | C<TGS>). | |
229 | ||
230 | =item NOSEAL | |
231 | ||
232 | The Ticket Granting Service cannot use the contents of this entry's key | |
233 | field as an encryption key (hexadecimal equivalent is C<0x020>, default is | |
234 | C<SEAL>). | |
235 | ||
236 | =item NOCPW | |
237 | ||
238 | The user cannot change his or her own password or key (hexadecimal | |
239 | equivalent is C<0x040>, default is C<CPW>). | |
240 | ||
241 | =back | |
242 | ||
243 | =item B<-expiration> <I<date of account expiration>> | |
244 | ||
245 | Determines when the entry itself expires. When a user entry expires, the | |
246 | user becomes unable to log in; when a server entry such as C<afs> expires, | |
247 | all server processes that use the associated key become inaccessible. | |
248 | Provide one of the three acceptable values: | |
249 | ||
250 | =over 4 | |
251 | ||
252 | =item never | |
253 | ||
254 | The account never expires (the default). | |
255 | ||
256 | =item I<mm/dd/yyyy> | |
257 | ||
258 | Sets the expiration date to 12:00 a.m. on the indicated date | |
259 | (month/day/year). Examples: C<01/23/1999>, C<10/07/2000>. | |
260 | ||
261 | =item "I<mm/dd/yyyy hh:MM>" | |
262 | ||
263 | Sets the expiration date to the indicated time (hours:minutes) on the | |
264 | indicated date (month/day/year). Specify the time in 24-hour format (for | |
265 | example, C<20:30> is 8:30 p.m.) Date format is the same as for a date | |
266 | alone. Surround the entire instance with quotes because it contains a | |
267 | space. Examples: C<"01/23/1999 22:30">, C<"10/07/2000 3:45">. | |
268 | ||
269 | =back | |
270 | ||
271 | Acceptable values for the year range from C<1970> (1 January 1970 is time | |
272 | 0 in the standard UNIX date representation) through C<2037> (2037 is the | |
273 | maximum because the UNIX representation cannot accommodate dates later | |
274 | than a value in February 2038). | |
275 | ||
276 | =item B<-lifetime> <I<maximum ticket lifetime>> | |
277 | ||
278 | Specifies the maximum lifetime that the Authentication Server's Ticket | |
279 | Granting Service (TGS) can assign to a ticket. If the account belongs to a | |
280 | user, this value is the maximum lifetime of a token issued to the user. If | |
281 | the account corresponds to a server such as C<afs>, this value is the | |
282 | maximum lifetime of a ticket that the TGS issues to clients for | |
283 | presentation to the server during mutual authentication. | |
284 | ||
285 | Specify an integer that represents a number of seconds (3600 equals one | |
286 | hour), or include a colon in the number to indicate a number of hours and | |
287 | minutes (C<10:00> equals 10 hours). If this argument is omitted, the | |
288 | default setting is 100:00 hours (360000 seconds). | |
289 | ||
290 | =item B<-pwexpires> <I<number of days password is valid>> | |
291 | ||
292 | Sets the number of days after the user's password was last changed that it | |
293 | remains valid. Provide an integer from the range C<1> through C<254> to | |
294 | specify the number of days until expiration, or the value C<0> to indicate | |
295 | that the password never expires (the default). | |
296 | ||
297 | When the password expires, the user is unable to authenticate, but has 30 | |
298 | days after the expiration date in which to use the B<kpasswd> command to | |
299 | change the password (after that, only an administrator can change it by | |
300 | using the B<kas setpassword> command). Note that the clock starts at the | |
301 | time the password was last changed, not when the B<kas setfields> command | |
302 | is issued. To avoid retroactive expiration, have the user change the | |
303 | password just before issuing a command that includes this argument. | |
304 | ||
305 | =item B<-reuse> (yes | no) | |
306 | ||
307 | Specifies whether or not the user can reuse any of his or her last 20 | |
308 | passwords. The acceptable values are C<yes> to allow reuse of old | |
309 | passwords (the default) and C<no> to prohibit reuse of a password that is | |
310 | similar to one of the previous 20 passwords. | |
311 | ||
312 | =item B<-attempts> <I<maximum successive failed login tries>> | |
313 | ||
314 | Sets the number of consecutive times the user can provide an incorrect | |
315 | password during authentication (using the B<klog> command or a login | |
316 | utility that grants AFS tokens). When the user exceeds the limit, the | |
317 | Authentication Server rejects further attempts (locks the user out) for | |
318 | the amount of time specified by the B<-locktime> argument. Provide an | |
319 | integer from the range C<1> through C<254> to specify the number of | |
320 | failures allowed, or C<0> to indicate that there is no limit on | |
321 | authentication attempts (the default value). | |
322 | ||
323 | =item B<-locktime> <I<failure penalty>> | |
324 | ||
325 | Specifies how long the Authentication Server refuses authentication | |
326 | attempts from a user who has exceeded the failure limit set by the | |
327 | B<-attempts> argument. | |
328 | ||
329 | Specify a number of hours and minutes (I<hh:mm>) or minutes only (I<mm>), | |
330 | from the range C<01> (one minute) through C<36:00> (36 hours). The B<kas> | |
331 | command interpreter automatically reduces any larger value to C<36:00> and | |
332 | also rounds up any non-zero value to the next higher multiple of 8.5 | |
333 | minutes. A value of C<0> (zero) sets an infinite lockout time; an | |
334 | administrator must issue the B<kas unlock> command to unlock the account. | |
335 | ||
336 | =item B<-admin_username> <I<admin principal>> | |
337 | ||
338 | Specifies the user identity under which to authenticate with the | |
339 | Authentication Server for execution of the command. For more details, see | |
340 | L<kas(8)>. | |
341 | ||
342 | =item B<-password_for_admin> <I<admin password>> | |
343 | ||
344 | Specifies the password of the command's issuer. If it is omitted (as | |
345 | recommended), the B<kas> command interpreter prompts for it and does not | |
346 | echo it visibly. For more details, see L<kas(8)>. | |
347 | ||
348 | =item B<-cell> <I<cell name>> | |
349 | ||
350 | Names the cell in which to run the command. For more details, see | |
351 | L<kas(8)>. | |
352 | ||
353 | =item B<-servers> <I<authentication servers>>+ | |
354 | ||
355 | Names each machine running an Authentication Server with which to | |
356 | establish a connection. For more details, see L<kas(8)>. | |
357 | ||
358 | =item B<-noauth> | |
359 | ||
360 | Assigns the unprivileged identity C<anonymous> to the issuer. For more | |
361 | details, see L<kas(8)>. | |
362 | ||
363 | =item B<-help> | |
364 | ||
365 | Prints the online help for this command. All other valid options are | |
366 | ignored. | |
367 | ||
368 | =back | |
369 | ||
370 | =head1 EXAMPLES | |
371 | ||
372 | In the following example, an administrator using the C<admin> account | |
373 | grants administrative privilege to the user C<smith>, and sets the | |
374 | Authentication Database entry to expire at midnight on 31 December 2000. | |
375 | ||
376 | % kas setfields -name smith -flags ADMIN -expiration 12/31/2000 | |
377 | Password for admin: | |
378 | ||
379 | In the following example, an administrator using the C<admin> account sets | |
380 | the user C<pat>'s password to expire in 60 days from when it last changed, | |
381 | and prohibits reuse of passwords. | |
382 | ||
383 | % kas setfields -name pat -pwexpires 60 -reuse no | |
384 | Password for admin: | |
385 | ||
386 | =head1 PRIVILEGE REQUIRED | |
387 | ||
388 | The issuer must have the C<ADMIN> flag set on his or her Authentication | |
389 | Database entry. | |
390 | ||
391 | =head1 SEE ALSO | |
392 | ||
393 | L<kaserverauxdb(5)>, | |
394 | L<kas(8)>, | |
395 | L<kas_examine(8)>, | |
396 | L<kas_setpassword(8)>, | |
397 | L<kas_unlock(8)>, | |
398 | L<klog(1)>, | |
399 | L<kpasswd(1)> | |
400 | ||
401 | =head1 COPYRIGHT | |
402 | ||
403 | IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved. | |
404 | ||
405 | This documentation is covered by the IBM Public License Version 1.0. It was | |
406 | converted from HTML to POD by software written by Chas Williams and Russ | |
407 | Allbery, based on work by Alf Wachsmann and Elizabeth Cassell. |