mirror of
https://git.openafs.org/openafs.git
synced 2025-01-19 07:20:11 +00:00
109 lines
4.0 KiB
Plaintext
109 lines
4.0 KiB
Plaintext
=head1 NAME
|
|
|
|
asetkey - Add a key from a keytab to an AFS KeyFile
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
=for html
|
|
<div class="synopsis">
|
|
|
|
B<asetkey> add <I<kvno>> <I<keyfile>> <I<principal>>
|
|
|
|
B<asetkey> delete <I<kvno>>
|
|
|
|
B<asetkey> list
|
|
|
|
=for html
|
|
</div>
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
The B<asetkey> command is used to add a key to an AFS KeyFile from a
|
|
Kerberos keytab. It is similar to B<bos addkey> except that it must be
|
|
run locally on the system where the KeyFile is located and it takes the
|
|
new key from a Kerberos 5 keytab rather than prompting for the password.
|
|
|
|
B<asetkey delete> can be used to delete a key (similar to B<bos
|
|
removekeys>), and B<asetkey list> will list the keys in a KeyFile (similar
|
|
to B<bos listkeys>).
|
|
|
|
B<asetkey> is used when authentication for an AFS cell is provided by a
|
|
Kerberos 5 KDC rather than B<kaserver>. The key for the C<afs> or
|
|
C<afs/I<cell name>> principal in the Kerberos 5 KDC must match the key
|
|
stored in the AFS KeyFile on all AFS database servers and file servers.
|
|
This is done by creating a keytab containing that key using the standard
|
|
Kerberos commands (generally the C<ktadd> function of the B<kadmin>
|
|
command) and then, on each AFS database server and file server, adding
|
|
that key to the KeyFile with B<asetkey add>. The I<kvno> chosen should
|
|
match the kvno in the Kerberos KDC (checked with B<kvno> or the
|
|
C<getprinc> function of B<kadmin>). I<principal> should be the name of
|
|
the AFS principal in the keytab, which must be either C<afs> or
|
|
C<afs/I<cell name>>.
|
|
|
|
In cells that use the Update Server to distribute the contents of the
|
|
F</usr/afs/etc> directory, it is conventional to run B<asetkey add> only
|
|
on the control machine and then let the Update Server propagate the new
|
|
KeyFile to all other systems.
|
|
|
|
=head1 CAUTIONS
|
|
|
|
AFS currently only supports des-cbc-crc:v4 Kerberos keys. Make sure, when
|
|
creating the keytab with C<ktadd>, you pass C<-e des-cbc-crc:v4> to force
|
|
the encryption type. Otherwise, AFS authentication may not work.
|
|
|
|
As soon as a new keytab is created with C<ktadd>, new AFS service tickets
|
|
will use the new key. However, tokens formed from those service tickets
|
|
will only work if the new key is present in the KeyFile on the AFS file
|
|
server. There is therefore an outage window between when the new keytab
|
|
is created and when the key had been added to the KeyFile of all AFS
|
|
servers with B<asetkey>, during which newly obtained AFS tokens will not
|
|
work properly.
|
|
|
|
All of the KeyFile entries must match the key in the Kerberos KDC, but
|
|
each time C<ktadd> is run, it creates a new key. Either the Update Server
|
|
must be used to distribute the KeyFile to all servers or the same keytab
|
|
must be used with B<asetkey> on each server.
|
|
|
|
=head1 EXAMPLES
|
|
|
|
The following commands create a new keytab for the principal C<afs> and
|
|
then import the key into the KeyFile. Note the kvno in the output from
|
|
C<ktadd>.
|
|
|
|
% kadmin
|
|
Authenticating as principal rra/admin@stanford.edu with password.
|
|
Password for rra/admin@stanford.edu:
|
|
kadmin: ktadd -k /tmp/afs.keytab -e des-cbc-crc:v4 afs
|
|
Entry for principal afs with kvno 3, encryption type DES cbc mode
|
|
with CRC-32 added to keytab WRFILE:/tmp/afs.keytab.
|
|
kadmin: exit
|
|
% asetkey 3 /tmp/afs.keytab afs
|
|
|
|
You may want to use C<afs/I<cell name>> instead of C<afs>, particularly if
|
|
you may have multiple AFS cells for a single Kerberos realm.
|
|
|
|
=head1 PRIVILEGE REQUIRED
|
|
|
|
The issuer must be able to read (for B<asetkey list>) and write (for
|
|
B<asetkey add> and B<asetkey delete>) the KeyFile, normally
|
|
F</usr/afs/etc/KeyFile>. In practice, this means that the issuer must be
|
|
the local superuser C<root> on the AFS file server or database server.
|
|
For B<asetkey add>, the issuer must also be able to read the specified
|
|
keytab file.
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<KeyFile(5)>,
|
|
L<bos_addkey(8)>,
|
|
L<bos_listkeys(8)>,
|
|
L<bos_removekey(8)>,
|
|
kadmin(8),
|
|
kvno(1)
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
Copyright 2006 Russ Allbery <rra@stanford.edu>
|
|
|
|
This documentation is covered by the IBM Public License Version 1.0. This
|
|
man page was written by Russ Allbery for OpenAFS.
|