krb5 commit [krb5-1.14]: Improve keytab documentation

[Tom Yu]

https://github.com/krb5/krb5/commit/d82fc87568171e4be99835e69221820f54842f12
commit d82fc87568171e4be99835e69221820f54842f12
Author: Ben Kaduk <kaduk at mit.edu>
Date:   Mon Jan 26 11:15:42 2015 -0500

    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 at mit.edu: squashed two commits, condensed commit message]
    
    (cherry picked from commit b1e655b38b60a05d4d2e4e0d4aedb7a9c36ab93b)
    
    ticket: 8500
    version_fixed: 1.14.5

 doc/admin/admin_commands/k5srvutil.rst |   22 ++++++++++++----------
 doc/admin/install_kdc.rst              |   17 +++++++++++++++--
 2 files changed, 27 insertions(+), 12 deletions(-)

diff --git a/doc/admin/admin_commands/k5srvutil.rst b/doc/admin/admin_commands/k5srvutil.rst
index 0e30a8e..b873d90 100644
--- 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 af93899..f5959e6 100644
--- a/doc/admin/install_kdc.rst
+++ b/doc/admin/install_kdc.rst
@@ -328,8 +328,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
@@ -341,6 +341,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
 ~~~~~~~~~~~~~~~~~~~~