Documentation patch for changing krbtgt

[Russ Allbery]

Following up on a Zephyr discussion, here's a proposed patch to document
changing the krbtgt key.  Did I say anything inaccurate?

Index: admin.texinfo
===================================================================
--- admin.texinfo	(revision 18327)
+++ admin.texinfo	(working copy)
@@ -1401,6 +1401,7 @@
 * Policies::                    
 * Global Operations on the Kerberos Database::  
 * Cross-realm Authentication::  
+* Changing the krbtgt Key::
 @end menu
 
 @node Kadmin Options, Date Format, Administrating the Kerberos Database, Administrating the Kerberos Database
@@ -2428,7 +2429,7 @@
 This will have to wait until the next release.  *sigh*
 @end ignore
 
- at node Cross-realm Authentication,  , Global Operations on the Kerberos Database, Administrating the Kerberos Database
+ at node Cross-realm Authentication, Changing the krbtgt Key, Global Operations on the Kerberos Database, Administrating the Kerberos Database
 @section Cross-realm Authentication
 
 In order for a KDC in one realm to authenticate Kerberos users in a
@@ -2463,6 +2464,37 @@
 @value{COMPANY} recommends that TGT principal passwords be at least 26
 characters of random ASCII text.
 
+ at node Changing the krbtgt Key,  , Cross-realm Authentication, Administrating the Kerberos Database
+ at section Changing the krbtgt Key
+
+A Kerberos Ticket Granting Ticket (TGT) is a service ticket for the
+principal krbtgt/@i{REALM}.  The key for this principal is created when
+the Kerberos database is initialized and need not be changed.  However,
+it will only have the encryption types supported by the KDC at the time
+of the initial database creation.  To allow use of newer encryption
+types for the TGT, this key has to be changed.
+
+Changing this key using the normal @code{kadmin change_password} command
+would invalidate any previously issued TGTs.  Therefore, when changing
+this key, normally one should use the @b{-keepold} flag to
+ at code{change_password} to retain the previous key in the database as
+well as the new key.  For example:
+
+ at smallexample
+ at group
+ at b{kadmin:} change_password -randkey -keepold krbtgt/@value{PRIMARYREALM}@@@value{PRIMARYREALM}
+ at end group
+ at end smallexample
+
+There is currently no way to remove the old key without running
+ at code{change_password} without the @b{-keepold} flag (and thereby
+invalidating all existing TGTs).  After issuing this command, the old
+key is still valid and is still vulnerable to (for instance) brute force
+attacks.  To completely retire an old key or encryption type, it's
+therefore currently necessary to declare a flag day, run
+ at code{change_password} without the @b{-keepold} flag, and force all
+users to acquire new tickets.
+
 @node Application Servers, Backups of Secure Hosts, Administrating the Kerberos Database, Top
 @chapter Application Servers
 

-- 
Russ Allbery (rra at stanford.edu)             <http://www.eyrie.org/~eagle/>