small project: use keytab for stash file

[Ken Raeburn]

There is a project in our plans to support changing of the database  
master key and its encryption type.  Assuming we want the update to  
be doable with a live database, without shutting down KDCs, for both  
db2 and ldap database back ends, this means at least temporarily  
keeping more than one "master" key around, and knowing which one  
you're dealing with.  There's no key version number stored in the  
stash file.

Also, as has been reported in our RT database (tickets 194 and 5662),  
the stash file encoding is machine-dependent, so moving a stash file  
between architectures can make it unusable.

So, Sam asked me to write up a proposal for a small project to  
address the stash file issues specifically.

  ---

Our end goal is to move away from the special stash file format, and  
just use a keytab file.

Ideally, I think, the file should be accessed through the generic  
krb5 library keytab interfaces, though the type should be assumed to  
be FILE: or WRFILE: as appropriate, if just a pathname is given in  
the config file.  Some of this would be done in lib/kdb/ 
kdb_default.c:krb5_db_def_fetch_mkey; that should cover the programs  
reading the stash file in order to access the database.  For  
backwards compatibility, the current format needs to be supported  
too, and the byte-swapped version of it should be as well.  The byte  
order can usually be inferred from the enctype, as two bytes are  
stored but the only enctypes we support right now are under 256.  The  
stash file format is dependent on sizeof(int) as well, but there's  
probably other code in our tree that'll break if sizeof(int) isn't 4.

The kdb5_util program's handling of the stash file needs to be  
updated to generate the new form (perhaps borrowing code from  
ktutil), and gain an option to tell it to generate the old form.  It  
should also get a new command for reading an old-format stash file  
and converting it to the keytab form.  (It will need to look up the  
principal name and key version number, and should verify the key  
against the database.)  All of this should be documented.

Documentation: Some of our documentation tells an admin how to set up  
and maintain a KDC.  Any references to the stash file should be  
checked and updated as necessary.  New text should be written  
describing how to convert an existing stash file to keytab format; it  
should note that there is currently no way to do the reverse.  (Until  
the multiple-master-key code is added, this can just be an option  
without any strong recommendation.)  Text should also be written  
describing how to generate the stash file in the old format in case  
the admin might want to use it with an older-version KDC.

New tests should be written to verify:
  * the KDC (or just KDB library) can use old-format stash files,  
both byte orders (ignore PDP-11)
  * the KDC (or just KDB library) can use a one-entry keytab file
  * kdb5_util stash can write both old-format and keytab stashes
  * kdb5_util update_stash (or whatever it's called) reads both byte  
orders, generates correct output

The test cases can use saved copies of generated files for inputs and  
for comparison.  The last test will require setting up a database.

For now, I don't think it makes sense to try to infer the master-key  
principal name from the keytab contents, because we still need to  
support an external specification if a password is going to be given.

The current "fetch master key" interfaces do include a context that  
may have a handle on the database.  I don't know offhand if it does  
when the routine is called, or if that handle includes the master key  
principal name; if it does, using the name in the keytab lookup would  
probably be a good idea.  If not, we'll just have to require that the  
keytab not be used for anything but the master key, which is sensible  
anyways.  The code must not assume the principal is named "K/M".

(Note that a small addition to ktutil could probably allow loading a  
keytab or srvtab, and writing one entry in stash file format.  I  
don't consider it an important feature to have.)

I think that covers it.  (Have I missed anything?)  With  
documentation and test cases, I'd estimate 1-2 weeks for someone  
reasonably familiar with the code.

Ken