krb5 commit [krb5-1.11]: Document master key rollover

[Tom Yu]

https://github.com/krb5/krb5/commit/270243d3a620ad110fb4f7fa0993cac93727bcf4
commit 270243d3a620ad110fb4f7fa0993cac93727bcf4
Author: Greg Hudson <ghudson at mit.edu>
Date:   Fri Oct 25 12:30:48 2013 -0400

    Document master key rollover
    
    Add a new section to database.rst documenting the procedure for
    rolling the master key.
    
    (cherry picked from commit e4b5d426a1e1e00367cc44a9619535ab71b20393)
    
    ticket: 7748 (new)
    version_fixed: 1.11.4
    status: resolved

 doc/admin/database.rst |   51 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 51 insertions(+), 0 deletions(-)

diff --git a/doc/admin/database.rst b/doc/admin/database.rst
index a110d21..fd84434 100644
--- a/doc/admin/database.rst
+++ b/doc/admin/database.rst
@@ -475,6 +475,57 @@ Examples
     shell%
 
 
+Updating the master key
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Starting with release 1.7, :ref:`kdb5_util(8)` allows the master key
+to be changed using a rollover process, with minimal loss of
+availability.  To roll over the master key, follow these steps:
+
+#. On the master KDC, run ``kdb5_util list_mkeys`` to view the current
+   master key version number (KVNO).  If you have never rolled over
+   the master key before, this will likely be version 1::
+
+    $ kdb5_util list_mkeys
+    Master keys for Principal: K/M at KRBTEST.COM
+    KVNO: 1, Enctype: des-cbc-crc, Active on: Wed Dec 31 19:00:00 EST 1969 *
+
+#. On the master KDC, run ``kdb5_util use_mkey 1`` to ensure that a
+   master key activation list is present in the database.  This step
+   is unnecessary in release 1.11.4 or later, or if the database was
+   initially created with release 1.7 or later.
+
+#. On the master KDC, run ``kdb5_util add_mkey -s`` to create a new
+   master key and write it to the stash file.  Enter a secure password
+   when prompted.  If this is the first time you are changing the
+   master key, the new key will have version 2.  The new master key
+   will not be used until you make it active.
+
+#. Propagate the database to all slave KDCs, either manually or by
+   waiting until the next scheduled propagation.  If you do not have
+   any slave KDCs, you can skip this and the next step.
+
+#. On each slave KDC, run ``kdb5_util list_mkeys`` to verify that the
+   new master key is present, and then ``kdb5_util stash`` to write
+   the new master key to the slave KDC's stash file.
+
+#. On the master KDC, run ``kdb5_util use_mkey 2`` to begin using the
+   new master key.  Replace ``2`` with the version of the new master
+   key, as appropriate.  You can optionally specify a date for the new
+   master key to become active; by default, it will become active
+   immediately.  Prior to release 1.12, :ref:`kadmind(8)` must be
+   restarted for this change to take full effect.
+
+#. On the master KDC, run ``kdb5_util update_princ_encryption``.  This
+   command will iterate over the database and re-encrypt all keys in
+   the new master key.  If the database is large, the master KDC will
+   become unavailable while this command runs, but clients should fail
+   over to slave KDCs (if any are present) during this time period.
+
+#. On the master KDC, run ``kdb5_util purge_mkeys`` to clean up the
+   old master key.
+
+
 .. _ops_on_ldap:
 
 Operations on the LDAP database