[krbdev.mit.edu #7365] krb5-admin doc update: kdb5_util dump -ov no longer needed for per-princ policy info

["Jeff D'Angelo" via RT]

 >Submitter-Id:  net
 >Originator:    Jeff D'Angelo <jcd at psu.edu>
 >Organization:  The Pennsylvania State University
 >Confidential:  no
 >Synopsis:      krb5-admin doc outdated; `kdb5_util dump -ov` no longer 
required for per-princ policy info
 >Severity:      non-critical
 >Priority:      low
 >Category:      krb5-doc
 >Class:         doc-bug
 >Release:       suspect affects all between 1.2.2 and 1.10.3, verified 
1.10.2
 >Environment:   suspect all, verified Linux
System: Linux fedorashin 2.6.27.25-78.2.56.fc9.i686 #1 SMP Thu Jun 18 
12:47:50 EDT 2009 i686 i686 i386 GNU/Linux
Architecture: i686

 >Description:
         In doc/krb5-admin.html of the kerberos tarball, section
         Dumping-a-Kerberos-Database-to-a-File, the documentation declares
         that the only way to preserve per-principal policy information
         is to create a second dump file using the -ov switch as well
         as a normal default dump with no options; that this "bug" [1]
         is still current.  Between a review of the code [2], primarily
         src/kadmin/dbutil/kdb5_util.c and src/kadmin/dbutil/dump.c,
         and experimental dumps and loads on version 1.10.2, it appears
         that dump formats "kdb5_util load_dump version 6", the default
         since krb5-1.8, and "kdb5_util load_dump version 5", the default
         between krb5-1.2.2 and krb5-1.7.2 and available via the -r13
         switch in later versions, both contain this per-principal policy
         information.  Thus I conclude that the documentation has been
         out of date since krb5-1.2.2 and should be updated.

 >How-To-Repeat:
         1) Create or locate a krb5kdc database with some principals 
with policies set.
         2) Create a "regular" dump file from this database via 
`kdb5_util dump <filename>`
         3) Create an ovsec_adm_export dump file via `kdb5_util dump -ov 
<filename>`
         4) Create a new krb5kdc database with `kdb5_util create -s -r 
<realm-name>` [3]
         5) Load the regular dump file via `kdb5_util load <filename>`
         6) Load the ovsec_adm_export dump file via `kdb5_util load 
-update <filename>`
         7) Examine the new database for per-policy information and 
compare to old via:
         7a) kadmin:  getprinc <principal-name>
             and
         7b) Perform a dump in every format from the original and new
             databases and then run a diff(1) between files of 
corresponding format.

         Repeat this process steps #2 and later using the -r13, -b7,
         -b6 and -old switches to the `kdb5_util dump` command in step #2.

         The "bug" [1] was found to be still present in versions -b6 and 
-b7,
         but not in -r13 and the default.  No difference was detected
         between the database dumps when -r13 and the default (no switch)
         formats were used in step #2 [4].

 >Fix:
         Change the doc/krb5-admin.html documentation to remove these 
statements:

 > Currently, the only way to preserve per-principal policy information 
is to use this in conjunction with a normal dump.

and

 > There is currently a bug where the default dump format omits the
 > per-principal policy information. In order to dump all the data contained
 > in the Kerberos database, you must perform a normal dump (with no option
 > flags) and an additional dump using the "-ov" flag to a different file.

         Optional: Include a statement to the fact that this was 
corrected in krb5-1.2.2, such as:

 > Note: Per-principal policy information was not included in the 
default dump format until
 > krb5-1.2.2 (-r13 and newer).


         [1] Referenced in "There is currently a bug where the default
             dump format omits the per-principal policy
             information." at the end of doc/krb5-admin.html, section
             Dumping-a-Kerberos-Database-to-a-File.

         [2] From versions krb5-1.2, 1.2.1, 1.2.2, 1.2.3, 1.2.5, 1.2.8, 1.3,
             1.7.2, 1.8, 1.10.2, 1.10.3.

         [3] In a new folder, or otherwise preserve the old database from
             step #1.

         [4] Admittedly, I did not set automatic lockout due to failed
             attempts on principals in the original database, or else I
             would expect a difference in the latest default format when
             -r13 was used to transfer it.

-- 
Jeff