=head1 NAME

kasetkey - Manipulate AFS kaserver service principal keys

=head1 SYNOPSIS

B<kasetkey> [B<-dhv>] B<-a> I<admin> B<-i> [B<-p> I<password>]
    B<-k> I<keyfile>

B<kasetkey> [B<-dhv>] B<-a> I<admin> [B<-k> I<keyfile>] B<-D> I<service>

B<kasetkey> [B<-dhv>] B<-a> I<admin> [B<-k> I<keyfile>]
    [ B<-c> I<k5srvtab> | B<-r> ] B<-s> I<service> B<-f> I<srvtab>

=head1 DESCRIPTION

B<kasetkey> manipulates principals in an AFS kaserver, usually service
principals.  It's primarily designed for automatic generation of srvtabs
for keys without regular passwords, but it can be used to do other
automated tasks, authenticating from a srvtab.

To start using B<kasetkey>, obtain a srvtab for a principal with the ADMIN
flag set in the AFS kaserver.  Such a srvtab can be created from the
password of that principal using B<kasetkey> with the B<-i> flag.  Then,
use B<-s> to create a srvtab for a particular principal or B<-D> to delete
a principal from the Kerberos database, passing via B<-k> the path to the
srvtab containing the key for an ADMIN principal.  If you don't use B<-k>,
B<kasetkey> will prompt you for the password of the given ADMIN principal.

When generating a srvtab for a particular principal using B<-s>, you have
your choice of ways of setting the key for that principal.  The default is
to prompt you for a password, but usually that's not what you want.
Provide the B<-r> flag to set a random key, which is normally what you
want to do for a pure Kerberos v4 principal.  When synchronizing Kerberos
v5 with Kerberos v4, generate a keytab in Kerberos v5, convert it to a
srvtab using B<ktutil>, and then provide that srvtab to B<kasetkey> with
the B<-c> flag.  B<kasetkey> will then set the key in the AFS kaserver to
match.

B<kasetkey> uses a simple, brute-force approach to setting keys in the AFS
kaserver.  It creates the principal if it doesn't already exist, and if it
does already exist, it deletes it and then recreates it.

=head1 OPTIONS

=over 4

=item B<-a> I<admin>

The user as whom changes should be performed.  This user must have the
ADMIN flag set in the AFS kaserver.

=item B<-c> I<srvtab>

When creating a service principal using B<-s>, take the key for that
principal from I<srvtab>.  I<srvtab> must contain a DES key and can be
created via B<ktutil> from a Kerberos v5 keytab.

=item B<-D> I<service>

Delete the principal I<service> from the AFS kaserver.

=item B<-d>

Turn on debugging.  This prints out more information about the exit status
of all of the API calls used.

=item B<-f> I<srvtab>

Where to write the srvtab for a newly created (or modified) principal.
Used only with B<-s>.

=item B<-h>

Display an option summary and a few examples and then exit.

=item B<-i>

Initialize a srvtab.  Takes the user from B<-a> and either prompts for the
password or takes it from the B<-p> flag.  Writes out the srvtab to the
path given to B<-k>.

=item B<-k> I<srvtab>

The srvtab to use to authenticate.  The key in the srvtab must be the key
for the user given with B<-a>.

=item B<-p> I<password>

The password for the user for which a srvtab is being initialized.  This
is only used with the B<-i> flag.

=item B<-r>

When generating a new srvtab with B<-s>, randomize the key for that user.

=item B<-s> I<service>

Create a new srvtab for the principal I<service>.  If this principal
already exists, it's deleted and recreated.  Takes the key for the
principal from the srvtab specified with B<-c>, randomizes it if B<-r> is
given, or prompts for it.

=item B<-v>

Prints the version of B<kasetkey> and exits.

=back

=head1 EXAMPLES

To create a srvtab for rcmd.slapshot and be prompted for the admin
passowrd:

    kasetkey -f srvtab.rcmd.slapshot -s rcmd.slapshot -r

To create a srvtab from within a script you must stash the DES key
in a srvtab with:

    kasetkey -a admin -i -k /.adminkey

(which will prompt you for the password) and then create a srvtab for
rcmd.slapshot with:

    kasetkey -k /.adminkey -a admin -r -f srvtab -s rcmd.slapshot

=head1 CAVEATS

The error reporting of this program is not great.  If an action fails, run
it again with the B<-d> flag, which will print out the return status of
every AFS operation.  You can then pass the failing error code to the
B<translate_et> program, installed with AFS, to translate the code into an
error message.

=head1 SEE ALSO

kas(8), kaserver(8), ktutil(8)

This program is part of the wallet system.  The current version is available
from L<http://www.eyrie.org/~eagle/software/wallet/>.

=head1 AUTHORS

Originally written by Roland Schemers.  Revised to use srvtabs rather than
simple DES keys and to support principal deletion by Russ Allbery
<rra@stanford.edu>, who currently maintains it.

=cut