Provided by: openafs-kpasswd_1.4.1-2_i386 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. the klog(1) manpage 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
       /etc/openafs/server-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 hexidecimal 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 the kas(8) manpage.

       -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 the kas(8) manpage.

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

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

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

       -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

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

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.