KAS_SETFIELDS(8) AFS Command Reference KAS_SETFIELDS(8)NAMEkas_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 /usr/afs/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 ALSOkaserverauxdb(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.
OpenAFS 2013-10-09 KAS_SETFIELDS(8)
