Provided by: openafs-kpasswd_1.6.7-1ubuntu1.1_amd64 bug

NAME

       kas_setfields - Sets fields in an Authentication Database entry

SYNOPSIS

       kas setfields -name <name of user>
           [-flags <hex flag value or flag name expression>]
           [-expiration <date of account expiration>]
           [-lifetime <maximum ticket lifetime>]
           [-pwexpires <number days password is valid ([0..254])>]
           [-reuse <permit password reuse (yes/no)>]
           [-attempts <maximum successive failed login tries ([0..254])>]
           [-locktime <failure penalty [hh:mm or minutes]>]
           [-admin_username <admin principal to use for authentication>]
           [-password_for_admin <admin password>] [-cell <cell name>]
           [-servers <explicit list of authentication servers>+]
           [-noauth] [-help]

       kas setf -na <name of user>
           [-f <hex flag value or flag name expression>]
           [-e <date of account expiration>]
           [-li <maximum ticket lifetime>]
           [-pw <number days password is valid ([0..254])>]
           [-r <permit password reuse (yes/no)>]
           [-at <maximum successive failed login tries ([0..254])>]
           [-lo <failure penalty [hh:mm or minutes]>]
           [-ad <admin principal to use for authentication>]
           [-pa <admin password>] [-c <cell name>]
           [-s <explicit list of authentication servers>+] [-no] [-h]

       kas sf -na <name of user>
           [-f <hex flag value or flag name expression>]
           [-e <date of account expiration>]
           [-li <maximum ticket lifetime>]
           [-pw <number days password is valid ([0..254])>]
           [-r <permit password reuse (yes/no)>]
           [-at <maximum successive failed login tries ([0..254])>]
           [-lo <failure penalty [hh:mm or minutes]>]
           [-ad <admin principal to use for authentication>]
           [-pa <admin password>] [-c <cell name>]
           [-s <explicit list of authentication servers>+] [-no] [-h]

DESCRIPTION

       The kas setfields command changes the Authentication Database entry for the user named by
       the -name argument in the manner specified by the various optional arguments, which can
       occur singly or in combination:

       •   To set the flags that determine whether the user has administrative privileges to the
           Authentication Server, can obtain a ticket, can change his or her password, and so on,
           include the -flags argument.

       •   To set when the Authentication Database entry expires, include the -expiration
           argument.

       •   To set the maximum ticket lifetime associated with the entry, include the -lifetime
           argument. klog(1) explains how this value interacts with others to determine the
           actual lifetime of a token.

       •   To set when the user's password expires, include the -pwexpires argument.

       •   To set whether the user can reuse any of the previous twenty passwords when creating a
           new one, include the -reuse argument.

       •   To set the maximum number of times the user can provide an incorrect password before
           the Authentication Server refuses to accept any more attempts (locks the issuer out),
           include the -attempts argument.  After the sixth failed authentication attempt, the
           Authentication Server logs a message in the UNIX system log file (the syslog file or
           equivalent, for which the standard location varies depending on the operating system).

       •   To set how long the Authentication Server refuses to process authentication attempts
           for a locked-out user, set the -locktime argument.

       The kas examine command displays the settings made with this command.

CAUTIONS

       The password lifetime set with the -pwexpires argument begins at the time the user's
       password was last changed, rather than when this command is issued. It can therefore be
       retroactive. If, for example, a user changed her password 100 days ago and the password
       lifetime is set to 100 days or less, the password effectively expires immediately.  To
       avoid retroactive expiration, instruct the user to change the password just before setting
       a password lifetime.

       Administrators whose authentication accounts have the "ADMIN" flag enjoy complete access
       to the sensitive information in the Authentication Database. To prevent access by
       unauthorized users, use the -attempts argument to impose a fairly strict limit on the
       number of times that a user obtaining administrative tokens can provide an incorrect
       password. Note, however, that there must be more than one account in the cell with the
       "ADMIN" flag. The kas unlock command requires the "ADMIN" privilege, so it is important
       that the locked-out administrator (or a colleague) can access another "ADMIN"-privileged
       account to unlock the current account.

       In certain circumstances, the mechanism used to enforce the number of failed
       authentication attempts can cause a lockout even though the number of failed attempts is
       less than the limit set by the -attempts argument. Client-side authentication programs
       such as klog and an AFS-modified login utility normally choose an Authentication Server at
       random for each authentication attempt, and in case of a failure are likely to choose a
       different Authentication Server for the next attempt. The Authentication Servers running
       on the various database server machines do not communicate with each other about how many
       times a user has failed to provide the correct password to them. Instead, each
       Authentication Server maintains its own separate copy of the auxiliary database file
       kaserverauxdb (located in the /var/lib/openafs/local directory by default), which records
       the number of consecutive authentication failures for each user account and the time of
       the most recent failure. This implementation means that on average each Authentication
       Server knows about only a fraction of the total number of failed attempts. The only way to
       avoid allowing more than the number of attempts set by the -attempts argument is to have
       each Authentication Server allow only some fraction of the total. More specifically, if
       the limit on failed attempts is f, and the number of Authentication Servers is S, then
       each Authentication Server can only permit a number of attempts equal to f divided by S
       (the Ubik synchronization site for the Authentication Server tracks any remainder, f mod
       S).

       Normally, this implementation does not reduce the number of allowed attempts to less than
       the configured limit (f). If one Authentication Server refuses an attempt, the client
       contacts another instance of the server, continuing until either it successfully
       authenticates or has contacted all of the servers. However, if one or more of the
       Authentication Server processes is unavailable, the limit is effectively reduced by a
       percentage equal to the quantity U divided by S, where U is the number of unavailable
       servers and S is the number normally available.

       To avoid the undesirable consequences of setting a limit on failed authentication
       attempts, note the following recommendations:

       •   Do not set the -attempts argument (the limit on failed authentication attempts) too
           low. A limit of nine failed attempts is recommended for regular user accounts, to
           allow three failed attempts per Authentication Server in a cell with three database
           server machines.

       •   Set fairly short lockout times when including the -locktime argument. Although
           guessing passwords is a common method of attack, it is not a very sophisticated one.
           Setting a lockout time can help discourage attackers, but excessively long times are
           likely to be more of a burden to authorized users than to potential attackers. A
           lockout time of 25 minutes is recommended for regular user accounts.

       •   Do not assign an infinite lockout time on an account (by setting the -locktime
           argument to 0 [zero]) unless there is a highly compelling reason. Such accounts almost
           inevitably become locked at some point, because each Authentication Server never
           resets the account's failure counter in its copy of the kaauxdb file (in contrast,
           when the lockout time is not infinite, the counter resets after the specified amount
           of time has passed since the last failed attempt to that Authentication Server).
           Furthermore, the only way to unlock an account with an infinite lockout time is for an
           administrator to issue the kas unlock command. It is especially dangerous to set an
           infinite lockout time on an administrative account; if all administrative accounts
           become locked, the only way to unlock them is to shut down all instances of the
           Authentication Server and remove the kaauxdb file on each.

OPTIONS

       -name <name of user>
           Names the Authentication Database account for which to change settings.

       -flags <hex flag or flag name expression>
           Sets one or more of four toggling flags, adding them to any flags currently set.
           Either specify one or more of the following strings, or specify a hexadecimal number
           that combines the indicated values. To return all four flags to their defaults,
           provide a value of 0 (zero). To set more than one flag at once using the strings,
           connect them with plus signs (example: "NOTGS+ADMIN+CPW"). To remove all the current
           flag settings before setting new ones, precede the list with an equal sign (example:
           "=NOTGS+ADMIN+CPW").

           ADMIN
               The user is allowed to issue privileged kas commands (hexadecimal equivalent is
               0x004, default is "NOADMIN").

           NOTGS
               The Authentication Server's Ticket Granting Service (TGS) refuses to issue tickets
               to the user (hexadecimal equivalent is 0x008, default is "TGS").

           NOSEAL
               The Ticket Granting Service cannot use the contents of this entry's key field as
               an encryption key (hexadecimal equivalent is 0x020, default is "SEAL").

           NOCPW
               The user cannot change his or her own password or key (hexadecimal equivalent is
               0x040, default is "CPW").

       -expiration <date of account expiration>
           Determines when the entry itself expires. When a user entry expires, the user becomes
           unable to log in; when a server entry such as "afs" expires, all server processes that
           use the associated key become inaccessible.  Provide one of the three acceptable
           values:

           never
               The account never expires (the default).

           mm/dd/yyyy
               Sets the expiration date to 12:00 a.m. on the indicated date (month/day/year).
               Examples: "01/23/1999", "10/07/2000".

           "mm/dd/yyyy hh:MM"
               Sets the expiration date to the indicated time (hours:minutes) on the indicated
               date (month/day/year). Specify the time in 24-hour format (for example, "20:30" is
               8:30 p.m.) Date format is the same as for a date alone. Surround the entire
               instance with quotes because it contains a space. Examples: "01/23/1999 22:30",
               "10/07/2000 3:45".

           Acceptable values for the year range from 1970 (1 January 1970 is time 0 in the
           standard UNIX date representation) through 2037 (2037 is the maximum because the UNIX
           representation cannot accommodate dates later than a value in February 2038).

       -lifetime <maximum ticket lifetime>
           Specifies the maximum lifetime that the Authentication Server's Ticket Granting
           Service (TGS) can assign to a ticket. If the account belongs to a user, this value is
           the maximum lifetime of a token issued to the user. If the account corresponds to a
           server such as "afs", this value is the maximum lifetime of a ticket that the TGS
           issues to clients for presentation to the server during mutual authentication.

           Specify an integer that represents a number of seconds (3600 equals one hour), or
           include a colon in the number to indicate a number of hours and minutes ("10:00"
           equals 10 hours). If this argument is omitted, the default setting is 100:00 hours
           (360000 seconds).

       -pwexpires <number of days password is valid>
           Sets the number of days after the user's password was last changed that it remains
           valid. Provide an integer from the range 1 through 254 to specify the number of days
           until expiration, or the value 0 to indicate that the password never expires (the
           default).

           When the password expires, the user is unable to authenticate, but has 30 days after
           the expiration date in which to use the kpasswd command to change the password (after
           that, only an administrator can change it by using the kas setpassword command). Note
           that the clock starts at the time the password was last changed, not when the kas
           setfields command is issued. To avoid retroactive expiration, have the user change the
           password just before issuing a command that includes this argument.

       -reuse (yes | no)
           Specifies whether or not the user can reuse any of his or her last 20 passwords. The
           acceptable values are "yes" to allow reuse of old passwords (the default) and "no" to
           prohibit reuse of a password that is similar to one of the previous 20 passwords.

       -attempts <maximum successive failed login tries>
           Sets the number of consecutive times the user can provide an incorrect password during
           authentication (using the klog command or a login utility that grants AFS tokens).
           When the user exceeds the limit, the Authentication Server rejects further attempts
           (locks the user out) for the amount of time specified by the -locktime argument.
           Provide an integer from the range 1 through 254 to specify the number of failures
           allowed, or 0 to indicate that there is no limit on authentication attempts (the
           default value).

       -locktime <failure penalty>
           Specifies how long the Authentication Server refuses authentication attempts from a
           user who has exceeded the failure limit set by the -attempts argument.

           Specify a number of hours and minutes (hh:mm) or minutes only (mm), from the range 01
           (one minute) through "36:00" (36 hours). The kas command interpreter automatically
           reduces any larger value to "36:00" and also rounds up any non-zero value to the next
           higher multiple of 8.5 minutes. A value of 0 (zero) sets an infinite lockout time; an
           administrator must issue the kas unlock command to unlock the account.

       -admin_username <admin principal>
           Specifies the user identity under which to authenticate with the Authentication Server
           for execution of the command. For more details, see kas(8).

       -password_for_admin <admin password>
           Specifies the password of the command's issuer. If it is omitted (as recommended), the
           kas command interpreter prompts for it and does not echo it visibly. For more details,
           see kas(8).

       -cell <cell name>
           Names the cell in which to run the command. For more details, see kas(8).

       -servers <authentication servers>+
           Names each machine running an Authentication Server with which to establish a
           connection. For more details, see kas(8).

       -noauth
           Assigns the unprivileged identity "anonymous" to the issuer. For more details, see
           kas(8).

       -help
           Prints the online help for this command. All other valid options are ignored.

EXAMPLES

       In the following example, an administrator using the "admin" account grants administrative
       privilege to the user "smith", and sets the Authentication Database entry to expire at
       midnight on 31 December 2000.

          % kas setfields -name smith -flags ADMIN -expiration 12/31/2000
          Password for admin:

       In the following example, an administrator using the "admin" account sets the user "pat"'s
       password to expire in 60 days from when it last changed, and prohibits reuse of passwords.

          % kas setfields -name pat -pwexpires 60 -reuse no
          Password for admin:

PRIVILEGE REQUIRED

       The issuer must have the "ADMIN" flag set on his or her Authentication Database entry.

SEE ALSO

       kaserverauxdb(5), kas(8), kas_examine(8), kas_setpassword(8), kas_unlock(8), klog(1),
       kpasswd(1)

COPYRIGHT

       IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.

       This documentation is covered by the IBM Public License Version 1.0.  It was converted
       from HTML to POD by software written by Chas Williams and Russ Allbery, based on work by
       Alf Wachsmann and Elizabeth Cassell.