doc/man-pages/pod8/kas_setfields.pod

   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.