| 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. |