3dd3d2805e861b0912363c41c69804959dd2aee9
[openafs.git] / doc / man-pages / pod8 / asetkey.pod
1 =head1 NAME
2
3 asetkey - Add a key from a keytab to an AFS KeyFile
4
5 =head1 SYNOPSIS
6
7 =for html
8 <div class="synopsis">
9
10 B<asetkey> add <I<kvno>> <I<keyfile>> <I<principal>>
11
12 B<asetkey> add <I<kvno>> <I<key>>
13
14 B<asetkey> add <I<type>> <I<kvno>> <I<subtype>> <I<key>>
15
16 B<asetkey> add <I<type>> <I<kvno>> <I<subtype>> <I<keyfile>> <I<princ>>
17
18 B<asetkey> delete <I<kvno>>
19
20 B<asetkey> list
21
22 =for html
23 </div>
24
25 =head1 DESCRIPTION
26
27 The B<asetkey> command is used to add a key to an AFS KeyFile or KeyFileExt
28 from a Kerberos keytab.  It is similar to B<bos addkey> except that it must be
29 run locally on the system where the KeyFile is located and it takes the
30 new key from the command line or a Kerberos 5 keytab rather than prompting
31 for the password.
32
33 B<asetkey delete> can be used to delete a key (similar to B<bos
34 removekeys>), and B<asetkey list> will list the keys in a KeyFile (similar
35 to B<bos listkeys>).
36
37 B<asetkey> is used when authentication for an AFS cell is provided by a
38 Kerberos 5 KDC rather than B<kaserver>.  The key for the C<afs> or
39 C<afs/I<cell name>> principal in the Kerberos 5 KDC must match the key
40 stored in the AFS KeyFile on all AFS database servers and file servers.
41 This is done by creating a keytab containing that key using the standard
42 Kerberos commands (generally the C<ktadd> function of the B<kadmin>
43 command) and then, on each AFS database server and file server, adding
44 that key to the KeyFile with B<asetkey add>.  The I<kvno> chosen should
45 match the kvno in the Kerberos KDC (checked with B<kvno> or the
46 C<getprinc> function of B<kadmin>).  I<principal> should be the name of
47 the AFS principal in the keytab, which must be either C<afs> or
48 C<afs/I<cell name>>. B<asetkey> can also be used to install a key
49 from a hex string.
50
51 In cells that use the Update Server to distribute the contents of the
52 F</usr/afs/etc> directory, it is conventional to run B<asetkey add> only
53 on the control machine and then let the Update Server propagate the new
54 KeyFile to all other systems.
55
56 =head1 CAUTIONS
57
58 Historically, AFS only supported des-cbc-crc:v4 Kerberos keys.  In environments
59 which have not been upgraded to use the rxkad-k5 extension, when
60 creating the keytab with C<ktadd>, you must pass C<-e des-cbc-crc:v4> to force
61 the encryption type.  Otherwise, AFS authentication may not work.
62
63 As soon as a new keytab is created with C<ktadd>, new AFS service tickets
64 will use the new key.  However, tokens formed from those service tickets
65 will only work if the new key is present in the KeyFile on the AFS file
66 server.  There is therefore an outage window between when the new keytab
67 is created and when the key had been added to the KeyFile of all AFS
68 servers with B<asetkey>, during which newly obtained AFS tokens will not
69 work properly.
70
71 All of the KeyFile entries must match the key in the Kerberos KDC, but
72 each time C<ktadd> is run, it creates a new key.  Either the Update Server
73 or some other mechanism must be used to distribute the KeyFile to all servers,
74 or the same keytab must be used with B<asetkey> on each server.
75
76 =head1 EXAMPLES
77
78 In a cell which is using the rxkad-k5 extension, the following commands
79 create a new keytab for the principal C<afs/I<cell name>> and then import
80 its keys into the KeyFileExt.  Note the kvno in the output from C<ktadd>.
81 The values 18, 17, and 16 are the assigned numbers corresponding to the
82 kerberos enctypes in the keytab.  These numbers can be determined from your
83 system's krb5 headers.
84
85     % kadmin
86     Authenticating as principal kaduk/admin@ZONE.MIT.EDU with password.
87     Password for kaduk/admin@ZONE.MIT.EDU:
88     kadmin:  ktadd -k /tmp/afs.keytab afs/disarray.mit.edu
89     Entry for principal afs/disarray.mit.edu with kvno 4, encryption type
90     aes256-cts-hmac-sha1-96 added to keytab WRFILE:/tmp/afs.keytab.
91     Entry for principal afs/disarray.mit.edu with kvno 4, encryption type
92     aes128-cts-hmac-sha1-96 added to keytab WRFILE:/tmp/afs.keytab.
93     Entry for principal afs/disarray.mit.edu with kvno 4, encryption type
94     des3-cbc-sha1 added to keytab WRFILE:/tmp/afs.keytab.
95     kadmin:  exit
96     % asetkey add rxkad_krb5 4 18 /tmp/afs.keytab afs/disarray.mit.edu
97     % asetkey add rxkad_krb5 4 17 /tmp/afs.keytab afs/disarray.mit.edu
98     % asetkey add rxkad_krb5 4 16 /tmp/afs.keytab afs/disarray.mit.edu
99
100 In a cell which is <B<not>> using the rxkad-k5 extension, the following
101 commands create a new keytab for the principal C<afs> and then import the
102 key into the KeyFile.  Note the kvno in the output from C<ktadd>.
103
104     % kadmin
105     Authenticating as principal rra/admin@stanford.edu with password.
106     Password for rra/admin@stanford.edu:
107     kadmin:  ktadd -k /tmp/afs.keytab -e des-cbc-crc:v4 afs
108     Entry for principal afs with kvno 3, encryption type DES cbc mode
109     with CRC-32 added to keytab WRFILE:/tmp/afs.keytab.
110     kadmin:  exit
111     % asetkey add 3 /tmp/afs.keytab afs
112
113 You may want to use C<afs/I<cell name>> instead of C<afs>, particularly if
114 you may have multiple AFS cells for a single Kerberos realm.
115
116 In the event you have been distributed a key by a Kerberos administrator
117 in the form of a hex string, you may use asetkey to install that.
118
119     % asetkey add 3 80b6a7cd7a9dadb6
120
121 I<key> should be an 8 byte hex representation.
122
123 =head1 PRIVILEGE REQUIRED
124
125 The issuer must be able to read (for B<asetkey list>) and write (for
126 B<asetkey add> and B<asetkey delete>) the KeyFile, normally
127 F</usr/afs/etc/KeyFile>.  In practice, this means that the issuer must be
128 the local superuser C<root> on the AFS file server or database server.
129 For B<asetkey add>, the issuer must also be able to read the specified
130 keytab file.
131
132 =head1 SEE ALSO
133
134 L<KeyFile(5)>,
135 L<bos_addkey(8)>,
136 L<bos_listkeys(8)>,
137 L<bos_removekey(8)>,
138 kadmin(8),
139 kvno(1)
140
141 =head1 COPYRIGHT
142
143 Copyright 2006 Russ Allbery <rra@stanford.edu>
144
145 This documentation is covered by the IBM Public License Version 1.0.  This
146 man page was written by Russ Allbery for OpenAFS.