[28011] in CVS-changelog-for-Kerberos-V5
krb5 commit [krb5-1.11]: Document master key rollover
daemon@ATHENA.MIT.EDU (Tom Yu)
Wed Oct 30 17:43:39 2013
Date: Wed, 30 Oct 2013 17:43:28 -0400
From: Tom Yu <tlyu@mit.edu>
Message-Id: <201310302143.r9ULhSBA022948@drugstore.mit.edu>
To: cvs-krb5@mit.edu
Reply-To: krbdev@mit.edu
MIME-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: 7bit
Errors-To: cvs-krb5-bounces@mit.edu
https://github.com/krb5/krb5/commit/270243d3a620ad110fb4f7fa0993cac93727bcf4
commit 270243d3a620ad110fb4f7fa0993cac93727bcf4
Author: Greg Hudson <ghudson@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@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
_______________________________________________
cvs-krb5 mailing list
cvs-krb5@mit.edu
https://mailman.mit.edu/mailman/listinfo/cvs-krb5
