Revision as of 17:31, 7 May 2008

Desired changes

The point of this small project is to change the format of the master key stash file to that of a keytab type file. This will allow the master key's KVNO to be stored along with its enctype and key data which in turn will enable an efficient implementation of master key updating.

Functional Requirements

The KDC must be able to access the most recent master key in the masterkey keytab and also retrieve a master key based on a given KVNO and or enctype. If the masterkey is stored in the old stash file format then the KDC will be backwards compatible and still be able to access the masterkey.

The utilities (kdb5_util, kdb_ldap_util, ktutil) must be able to read and write to a masterkey keytab. These utilities will also be able to read and old format stash file. They will not be able to write an old format stash file.

Design of implementation

The krb5_def_store_mkey() and krb5_db_def_fetch_mkey() functions would be modified to use the keytab functions found in libkrb5.

The krb5_db_def_fetch_mkey() function would first try to read the master key stash as a keytab file using krb5_kt_get_entry() and if that fails it would fall back to using the current stash code to treat the stash file as an old format stash file. Note that this function already has a kvno arg that can be used for input and output.

The krb5_def_store_mkey() interface would be modified to write a keytab and to accept an optional KVNO argument. It would need to deal with existing old stash format files so the code would test to see if the stash file existed and was non-0 size and if so, would first try reading it as a keytab. If the stash file is determined to be a keytab by a successful call to krb5_kt_get_entry() and the principal name is verified to be correct then krb5_kt_add_entry() would be called to add the new masterkey to the stash file.

If krb5_kt_get_entry() returned an error then the stash file would be truncated to 0 bytes and then krb5_kt_add_entry() would be called to add the masterkey entry. If the stash file did not exist or was 0 bytes in size then krb5_kt_add_entry() would be called directly. The reason for detecting and an existing old format stash file is to allow krb5_def_store_mkey() the ability to store > 1 masterkey. Since krb5_kt_add_entry() always appends to a keytab care must be taken to ensure the existing stash file is a keytab and not the old format stash.

Callers of krb5_def_store_mkey() would need to be modified to deal with the new KVNO argument. If a user specified KVNO was passed in and a key with that KVNO existed in the keytab, an error would be returned otherwise a new key with that KVNO would be added to the keytab. If a KVNO was not specified, the current behavior whose KVNO would either be 0 if no keys exist in the keytab or would be one greater than the largest KVNO found in the keytab.

The kdb5_util interface would be modified to allow the user to specify the KVNO. The code will return an error if kdb5_util attemps to add a key with a user specified KVNO to the masterkey keytab and a key with that same KVNO already exists in the keytab. At that point the user would either to use ktutil at that point to remove the existing key, specify a different KVNO, or just remove the keytab file and rerun the kdb5_util command.

Note the default file name convention currently used for stash files will be used for masterkey keytab files. One implication of this is that once an admin overwrites an existing old format stash file with the new keytab format there is no going back to the old format as kdb5_util will not support creation of the old format.

Tasks/milestones

• project start. Apr 3, 2008
• project review. ~2 week
• Implementation. ~2 week
• test. ~1 week
• code review. ~1 week
• documentation. ~1 day

Desired integration and release goals

Integrate and test before 1.7 release.

Testing plan

Unit testing of stash file related functions will be performed to make sure the krb5kdc, kadmind, kadmin, kadmin.local, kdb5_util, and ktutil are able to access and administer the masterkey keytab file. Tests will be done for these scenarios:

• An old format stash file exists. The krb5kdc and kadmind should be

able to read the masterkey. The kdb5_util stash and create commands should be able to overwrite the stash file.

• No stash exists. kdb5_util should be able to create a masterkey

keytab stash.

• The daemons that require masterkey access will be tested to validate

the ability to read the masterkey in a keytab.

Regression testing will be running the tests in the MIT source tree that test the function of the krb5kdc, kadmind, kadmin, kadmin.local, kdb5_util, and ktutil.

An old copy of a binary stash file will be checked in to the source tree to aid in regression testing.

Review

This section documents the review of the project according to Project policy. It is divided into multiple sections. First, approvals should be listed. To list an approval type

#~~~~

on its own line. The next section is for discussion. Use standard talk pageconventions. In particular, sign comments with

--~~~~

and indent replies.

Members of Krbcore raising Blocking objections should preface their comment with {{project-block}}. The member who raised the objection should remove this markup when their objection is handled.

Approvals

SamHartman 12:20, 4 April 2008 (EDT)

Discussion

I've noted approval but I'd like to ask you to consider a couple of issues:

• It would be good if an old format stash file was checked into the source tree and the regression tests run with make check confirm we can read that stash file.
• Please clearly document what happens when kt_get_entry doesn't find the right principal but does parse the file as a keytab?

--SamHartman 12:20, 4 April 2008 (EDT)