=head1 NAME

kas_setfields - Sets fields in an Authentication Database entry

=head1 SYNOPSIS

=for html
<div class="synopsis">

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

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

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

=for html
</div>

=head1 DESCRIPTION

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

=over 4

=item *

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 B<-flags> argument.

=item *

To set when the Authentication Database entry expires, include the
B<-expiration> argument.

=item *

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

=item *

To set when the user's password expires, include the B<-pwexpires>
argument.

=item *

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

=item *

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 B<-attempts> argument.  After
the sixth failed authentication attempt, the Authentication Server logs a
message in the UNIX system log file (the F<syslog> file or equivalent, for
which the standard location varies depending on the operating system).

=item *

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

=back

The B<kas examine> command displays the settings made with this command.

=head1 CAUTIONS

The password lifetime set with the B<-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 C<ADMIN> flag enjoy
complete access to the sensitive information in the Authentication
Database. To prevent access by unauthorized users, use the B<-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 C<ADMIN> flag. The B<kas unlock> command requires the
C<ADMIN> privilege, so it is important that the locked-out administrator
(or a colleague) can access another C<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 B<-attempts>
argument. Client-side authentication programs such as B<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 F<kaserverauxdb> (located in the F</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 B<-attempts> argument is to have each Authentication Server
allow only some fraction of the total. More specifically, if the limit on
failed attempts is I<f>, and the number of Authentication Servers is I<S>,
then each Authentication Server can only permit a number of attempts equal
to I<f> divided by I<S> (the Ubik synchronization site for the
Authentication Server tracks any remainder, I<f> mod I<S>).

Normally, this implementation does not reduce the number of allowed
attempts to less than the configured limit (I<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 I<U> divided by I<S>, where
I<U> is the number of unavailable servers and I<S> is the number normally
available.

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

=over 4

=item *

Do not set the B<-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.

=item *

Set fairly short lockout times when including the B<-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.

=item *

Do not assign an infinite lockout time on an account (by setting the
B<-locktime> argument to C<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 F<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 B<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 F<kaauxdb> file on each.

=back

=head1 OPTIONS

=over 4

=item B<-name> <I<name of user>>

Names the Authentication Database account for which to change settings.

=item B<-flags> <I<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 C<0> (zero). To set
more than one flag at once using the strings, connect them with plus signs
(example: C<NOTGS+ADMIN+CPW>). To remove all the current flag settings
before setting new ones, precede the list with an equal sign (example:
C<=NOTGS+ADMIN+CPW>).

=over 4

=item ADMIN

The user is allowed to issue privileged kas commands (hexadecimal
equivalent is C<0x004>, default is C<NOADMIN>).

=item NOTGS

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

=item NOSEAL

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

=item NOCPW

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

=back

=item B<-expiration> <I<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 C<afs> expires,
all server processes that use the associated key become inaccessible.
Provide one of the three acceptable values:

=over 4

=item never

The account never expires (the default).

=item I<mm/dd/yyyy>

Sets the expiration date to 12:00 a.m. on the indicated date
(month/day/year). Examples: C<01/23/1999>, C<10/07/2000>.

=item "I<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, C<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: C<"01/23/1999 22:30">, C<"10/07/2000 3:45">.

=back

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

=item B<-lifetime> <I<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 C<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 (C<10:00> equals 10 hours). If this argument is omitted, the
default setting is 100:00 hours (360000 seconds).

=item B<-pwexpires> <I<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 C<1> through C<254> to
specify the number of days until expiration, or the value C<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 B<kpasswd> command to
change the password (after that, only an administrator can change it by
using the B<kas setpassword> command). Note that the clock starts at the
time the password was last changed, not when the B<kas setfields> command
is issued. To avoid retroactive expiration, have the user change the
password just before issuing a command that includes this argument.

=item B<-reuse> (yes | no)

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

=item B<-attempts> <I<maximum successive failed login tries>>

Sets the number of consecutive times the user can provide an incorrect
password during authentication (using the B<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 B<-locktime> argument. Provide an
integer from the range C<1> through C<254> to specify the number of
failures allowed, or C<0> to indicate that there is no limit on
authentication attempts (the default value).

=item B<-locktime> <I<failure penalty>>

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

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

=item B<-admin_username> <I<admin principal>>

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

=item B<-password_for_admin> <I<admin password>>

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

=item B<-cell> <I<cell name>>

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

=item B<-servers> <I<authentication servers>>+

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

=item B<-noauth>

Assigns the unprivileged identity C<anonymous> to the issuer. For more
details, see L<kas(8)>.

=item B<-help>

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

=back

=head1 EXAMPLES

In the following example, an administrator using the C<admin> account
grants administrative privilege to the user C<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 C<admin> account sets
the user C<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:

=head1 PRIVILEGE REQUIRED

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

=head1 SEE ALSO

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

=head1 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.