Improve keytab documentation

In the k5srvutil man page, do not give the impression that arbitrary
new keys can be added to the keytab (requested by Dan Gillmor), since
only the new keys randomly generated by the KDC via 'k5srvutil change'
can be added to the keytab.  Reiterate the importance of running
k5srvutil delold after running k5srvutil change in the description of
k5srvutil change, as well as in the description of k5srvutil delold
itself.

In install_kdc.rst, mention using a separate keytab file when
generating a keytab on a KDC for use on another host.

[ghudson@mit.edu: squashed two commits, condensed commit message]

ticket: 8500

diff --git a/doc/admin/admin_commands/k5srvutil.rst b/doc/admin/admin_commands/k5srvutil.rst
index 0e30a8ea2a63bd4ed143b24d95f15ceb97d4fc13..b873d907774b4f0b94794901c03bfda6fe445be2 100644 (file)
--- a/doc/admin/admin_commands/k5srvutil.rst
+++ b/doc/admin/admin_commands/k5srvutil.rst
@@ -14,13 +14,14 @@ SYNOPSIS
 DESCRIPTION
 -----------
 
-k5srvutil allows an administrator to list or change keys currently in
-a keytab or to add new keys to the keytab.
+k5srvutil allows an administrator to list keys currently in
+a keytab, to obtain new keys for a principal currently in a keytab,
+or to delete non-current keys from a keytab.
 
 *operation* must be one of the following:
 
 **list**
-    Lists the keys in a keytab showing version number and principal
+    Lists the keys in a keytab, showing version number and principal
     name.
 
 **change**
@@ -28,13 +29,14 @@ a keytab or to add new keys to the keytab.
     database to new randomly-generated keys, and updates the keys in
     the keytab to match.  If a key's version number doesn't match the
     version number stored in the Kerberos server's database, then the
-    operation will fail.  Old keys are retained in the keytab so that
-    existing tickets continue to work.  If the **-i** flag is given,
-    k5srvutil will prompt for confirmation before changing each key.
-    If the **-k** option is given, the old and new keys will be
-    displayed.  Ordinarily, keys will be generated with the default
-    encryption types and key salts.  This can be overridden with the
-    **-e** option.
+    operation will fail.  If the **-i** flag is given, k5srvutil will
+    prompt for confirmation before changing each key.  If the **-k**
+    option is given, the old and new keys will be displayed.
+    Ordinarily, keys will be generated with the default encryption
+    types and key salts.  This can be overridden with the **-e**
+    option.  Old keys are retained in the keytab so that existing
+    tickets continue to work, but **delold** should be used after
+    such tickets expire, to prevent attacks against the old keys.
 
 **delold**
     Deletes keys that are not the most recent version from the keytab.

diff --git a/doc/admin/install_kdc.rst b/doc/admin/install_kdc.rst
index 1b4cc75dfa80a70bddfe2de8cb500fbf24dd77c0..1715d371e115619fa89f257accb8d797eff4065c 100644 (file)
--- a/doc/admin/install_kdc.rst
+++ b/doc/admin/install_kdc.rst
@@ -330,8 +330,8 @@ Next, extract ``host`` random keys for all participating KDCs and
 store them in each host's default keytab file.  Ideally, you should
 extract each keytab locally on its own KDC.  If this is not feasible,
 you should use an encrypted session to send them across the network.
-To extract a keytab on a slave KDC called ``kerberos-1.mit.edu``, you
-would execute the following command::
+To extract a keytab directly on a slave KDC called
+``kerberos-1.mit.edu``, you would execute the following command::
 
     kadmin: ktadd host/kerberos-1.mit.edu
     Entry for principal host/kerberos-1.mit.edu with kvno 2, encryption
@@ -343,6 +343,19 @@ would execute the following command::
     Entry for principal host/kerberos-1.mit.edu with kvno 2, encryption
         type arcfour-hmac added to keytab FILE:/etc/krb5.keytab.
 
+If you are instead extracting a keytab for the slave KDC called
+``kerberos-1.mit.edu`` on the master KDC, you should use a dedicated
+temporary keytab file for that machine's keytab:
+
+    kadmin: ktadd -k /tmp/kerberos-1.keytab host/kerberos-1.mit.edu
+    Entry for principal host/kerberos-1.mit.edu with kvno 2, encryption
+        type aes256-cts-hmac-sha1-96 added to keytab FILE:/etc/krb5.keytab.
+    Entry for principal host/kerberos-1.mit.edu with kvno 2, encryption
+        type aes128-cts-hmac-sha1-96 added to keytab FILE:/etc/krb5.keytab.
+
+The file ``/tmp/kerberos-1.keytab`` can then be installed as
+``/etc/krb5.keytab`` on the host ``kerberos-1.mit.edu``.
+
 
 Configure slave KDCs
 ~~~~~~~~~~~~~~~~~~~~