=head1 NAME

kas setpassword - Changes the key field in an Authentication Database entry

=head1 SYNOPSIS

kas setpassword B<-name> I<name of user>  [B<-new_password> I<new password>]
[B<-kvno> I<key version number>]
[B<-admin_username> I<admin principal to use for authentication>]
[B<-password_for_admin> I<admin password>]  [B<-cell> I<cell name>]
[B<-servers> I<explicit list of authentication servers> ...]
[B<-noauth>]  [B<-help>]

kas setpasswd B<-na> I<name of user>  [B<-ne> I<new password>]
[B<-k> I<key version number>]
[B<-a> I<admin principal to use for authentication>]
[B<-p> I<admin password>]  [B<-c> I<cell name>]
[B<-s> I<explicit list of authentication servers> ...]  [B<-no>]  [B<-h>]

kas setp B<-na> I<name of user>  [B<-ne> I<new password>]  [B<-k> I<key version number>]
[B<-a> I<admin principal to use for authentication>]
[B<-p> I<admin password>]  [B<-c> I<cell name>]
[B<-s> I<explicit list of authentication servers> ...]  [B<-no>]  [B<-h>]

kas sp B<-na> I<name of user>  [B<-ne> I<new password>]  [B<-k> I<key version number>]
[B<-a> I<admin principal to use for authentication >]
[B<-p> I<admin password>]  [B<-c> I<cell name>]
[B<-s> I<explicit list of authentication servers> ...]  [B<-no>]  [B<-h>]

=head1 DESCRIPTION

The C<kas setpassword> command accepts a character string of unlimited
length, scrambles it into a form suitable for use as an encryption
key, places it in the key field of the Authentication Database entry
named by the B<-name> argument, and assigns it the key version number
specified by the B<-kvno> argument.

To avoid making the password string visible at the shell prompt, omit
the B<-new_password> argument. Prompts then appear at the shell which do
not echo the password visibly.

When changing the B<afs> server key, also issue C<bos addkey> command to add
the key (with the same key version number) to the B</usr/afs/etc/KeyFile>
file. See the IBM AFS Administration Guide for instructions.

The command interpreter checks the password string subject to the
following conditions:

=over

=item *

If there is a program called B<kpwvalid> in the same directory as the
B<kas> binary, the command interpreter invokes it to process the
password. For details, see the L<kpwvalid(1)> reference page.

=item *

If the B<-reuse> argument to the C<kas setfields> command has been used
to prohibit reuse of previous passwords, the command interpreter
verifies that the password is not too similar too any of the
user's previous 20 passwords. It generates the following error
message at the shell:

 Password was not changed because it seems like a reused password

To prevent a user from subverting this restriction by changing the
password twenty times in quick succession (manually or by running
a script), use the B<-minhours> argument on the C<kaserver>
initialization command. The following error message appears if a
user attempts to change a password before the minimum time has
passed:

 Password was not changed because you changed it too
 recently; see your systems administrator

=back

=head1 OPTIONS

=over 4

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

Names the entry in which to record the new key.

=item B<-new_password> I<new password>

Specifies the character string the user types when
authenticating to AFS. Omit this argument and type the string
at the resulting prompts so that the password does not echo
visibly. Note that some non-AFS programs cannot handle
passwords longer than eight characters.

=item B<-kvno> I<key version number>

Specifies the key version number associated with the new key.
Provide an integer in the range from B<0> through B<255>. If omitted,
the default is 0 (zero), which is probably not desirable for
server keys.

=item B<-admin_username> I<admin principal to use for authentication>

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

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

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

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

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

=item B<-servers> I<explicit list of authentication servers> ...

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

=item B<-noauth>

Assigns the unprivileged identity B<anonymous> to the issuer. For
more details, see the introductory L<kas(1)> reference page.

=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 B<admin> account
changes the password for B<pat> (presumably because B<pat> forgot the former
password or got locked out of his account in some other way).

B<    kas setpassword pat>
   Password for admin:
   new_password:
   Verifying, please re-enter new_password:

=head1 PRIVILEGE REQUIRED

Individual users can change their own passwords. To change another
user's password or the password (server encryption key) for server
entries such as B<afs>, the issuer must have the C<ADMIN> flag set in his or
her Authentication Database entry.

=head1 COPYRIGHT

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

Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
Stanford Linear Accelerator Center, a department of Stanford University.

=head1 SEE ALSO

L<bos_addkey(1)>,
L<kas(1)>,
L<kaserver(1)>,
L<kpwvalid(1)>

=cut
