From fa8e0beb96c8693a98d5ce0f310255bcd0731f6f Mon Sep 17 00:00:00 2001 From: Benjamin Kaduk Date: Fri, 27 Feb 2015 17:47:45 -0500 Subject: [PATCH 1/1] Update asetkey.8 for KeyFileExt Prefer KeyFileExt to KeyFile ~everywhere. Make the main documentation assume a modern cell with KeyFileExt and rxkad-k5, moving the old rxkad and KeyFile documentation to a new section, HISTORICAL COMPATIBILITY. Note that kaserver is deprecated. Do not mention the Update Server, which is also disrecommended for new installations. Add a copyright statement for the new content. Change-Id: Idcb4940615a00189b655538a9a190cc35153cc89 Reviewed-on: http://gerrit.openafs.org/11769 Tested-by: BuildBot Reviewed-by: Benjamin Kaduk --- doc/man-pages/pod8/asetkey.pod | 87 ++++++++++++++++++++++++------------------ 1 file changed, 50 insertions(+), 37 deletions(-) diff --git a/doc/man-pages/pod8/asetkey.pod b/doc/man-pages/pod8/asetkey.pod index 3dd3d28..97ed37a 100644 --- a/doc/man-pages/pod8/asetkey.pod +++ b/doc/man-pages/pod8/asetkey.pod @@ -31,27 +31,24 @@ new key from the command line or a Kerberos 5 keytab rather than prompting for the password. B can be used to delete a key (similar to B), and B will list the keys in a KeyFile (similar -to B). +removekeys>), and B will list the keys in a KeyFile +and the keys in a KeyFileExt (similar to B, but more +fully featured, since B cannot list the contents of +a KeyFileExt). B is used when authentication for an AFS cell is provided by a -Kerberos 5 KDC rather than B. The key for the C or +Kerberos 5 KDC rather than the deprecated B. +The key for the C or C> principal in the Kerberos 5 KDC must match the key -stored in the AFS KeyFile on all AFS database servers and file servers. +stored in the AFS KeyFileExt 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 function of the B command) and then, on each AFS database server and file server, adding -that key to the KeyFile with B. The I chosen should +that key to the KeyFileExt with B. The I chosen should match the kvno in the Kerberos KDC (checked with B or the C function of B). I should be the name of the AFS principal in the keytab, which must be either C or -C>. B can also be used to install a key -from a hex string. - -In cells that use the Update Server to distribute the contents of the -F directory, it is conventional to run B only -on the control machine and then let the Update Server propagate the new -KeyFile to all other systems. +C>. =head1 CAUTIONS @@ -62,15 +59,15 @@ the encryption type. Otherwise, AFS authentication may not work. As soon as a new keytab is created with C, 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 +will only work if the new key is present in the KeyFileExt 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 +is created and when the key had been added to the KeyFileExt of all AFS servers with B, 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 is run, it creates a new key. Either the Update Server -or some other mechanism must be used to distribute the KeyFile to all servers, +All of the KeyFileExt entries must match the key in the Kerberos KDC, but +each time C is run, it creates a new key. Some secure mechanism +must be used to distribute the KeyFileExt to all servers, or the same keytab must be used with B on each server. =head1 EXAMPLES @@ -97,9 +94,38 @@ system's krb5 headers. % asetkey add rxkad_krb5 4 17 /tmp/afs.keytab afs/disarray.mit.edu % asetkey add rxkad_krb5 4 16 /tmp/afs.keytab afs/disarray.mit.edu -In a cell which is > using the rxkad-k5 extension, the following -commands create a new keytab for the principal C and then import the -key into the KeyFile. Note the kvno in the output from C. +=head1 PRIVILEGE REQUIRED + +The issuer must be able to read (for B) and write (for +B and B) the KeyFileExt, normally +F. In practice, this means that the issuer must be +the local superuser C on the AFS file server or database server. +For B, the issuer must also be able to read the specified +keytab file. + +=head1 HISTORICAL COMPATIBILITY + +A modern AFS cell should be using the rxkad-k5 extension, or risks +terribly insecure operation (complete cell compromise for $100 in +1 day). The keys used for rxkad-k5 operation are stored in the +KeyFileExt. Cells not using the rxkad-k5 extension (i.e., stock +rxkad) use keys of the des-cbc-crc encryption type, which are stored +in the KeyFile. + +B retains the functionality needed to support stock rxkad +operation, but its use is disrecommended. A bare 8-byte hex key +can be added with + + % asetkey add I I + +I should be an 8 byte hex representation. An example using +a kvno of 3: + + % asetkey add 3 80b6a7cd7a9dadb6 + +The following commands create a new keytab for the principal C +and then import the key into the KeyFile. Note the kvno in the +output from C. % kadmin Authenticating as principal rra/admin@stanford.edu with password. @@ -113,25 +139,10 @@ key into the KeyFile. Note the kvno in the output from C. You may want to use C> instead of C, particularly if you may have multiple AFS cells for a single Kerberos realm. -In the event you have been distributed a key by a Kerberos administrator -in the form of a hex string, you may use asetkey to install that. - - % asetkey add 3 80b6a7cd7a9dadb6 - -I should be an 8 byte hex representation. - -=head1 PRIVILEGE REQUIRED - -The issuer must be able to read (for B) and write (for -B and B) the KeyFile, normally -F. In practice, this means that the issuer must be -the local superuser C on the AFS file server or database server. -For B, the issuer must also be able to read the specified -keytab file. - =head1 SEE ALSO L, +L, L, L, L, @@ -141,6 +152,8 @@ kvno(1) =head1 COPYRIGHT Copyright 2006 Russ Allbery +Copyright 2013,2015 Massachusetts Institute of Technology This documentation is covered by the IBM Public License Version 1.0. This -man page was written by Russ Allbery for OpenAFS. +man page was written by Russ Allbery for OpenAFS and updated for the +rxkad-k5 extension by Benjamin Kaduk. -- 1.9.4