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