small project: use keytab for stash file
raeburn at MIT.EDU
Mon Oct 22 19:16:31 EDT 2007
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
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.
More information about the krbdev