Subject: Kerberos Master Key Migration [PSARC/2009/233 FastTrack timeout 04/17/2009] To: PSARC-ext@Sun.Com Cc: kerberos-discuss@opensolaris.org Bcc: one-pager-list@sac.sfbay one-pager-log@sac.sfbay sac-bar@sac.sfbay I'm sponsoring this fasttrack for Will Fiveash. We request Micro/Patch release binding (though with no intention to backport) the timeout is set for 2009-04-17. Nico This information is Copyright 2008 Sun Microsystems ABSTRACT -------- This case will provide the ability to add a new master key (with an enctype differing from the current master key) to the master key principal and stash file and then migrate the encryption of existing principals long term keys to use the new master key. In addition deletion of master keys will be provided. This function will be provided by resyncing that functionality that currently exists in the MIT Kerberos Consortium code base. BACKGROUND ---------- OpenSolaris Kerberos is based on MIT Kerberos V5 and is currently fully synced fully with 1.4 and parts of 1.6 (see http://opensolaris.org/os/project/kerberos/). The current release of MIT Kerberos is 1.7 and the new features include support for migrating the master key enctype (encryption type) to a new (and likely stronger) enctype. Previously it was not possible to change the enctype of the master key which is established at the time a principal DB (KDB) is created. Note that prior to Solaris 10 the only supported enctype was DES which is now regarded as a weak thus any KDCs created on earlier versions of Solaris are stuck with a DES master key. * See Also MITKC Projects/Master Key Migration http://k5wiki.kerberos.org/wiki/Projects/Master_Key_Migration PROPOSAL -------- In MIT Kerberos 1.7 support for master key enctype migration is introduced and will be added to OpenSolaris. The following is from the MITKC Projects/Master Key Migration webpage: =Functional Requirements= The KDC must be able to deal with multiple master keys and determine which key to use when decrypting a principal's long term secret key. The KDC must be able to access any of the master key (K/M) principal's keys as long as it has access to a master key that is in use. The administrator must be able re-encrypt principal keys using a specified mkey and be able to specifying the set of principals is to be re-encrypted. The command doing this must be able to determine if a principal's keys are protected by the current master key or not. This implies that some set of principals may be protected with a non-current master key. Slave KDCs must be able to access all master keys currently protecting principal entries and therefore have access to the principal's secret keys regardless of which master key is used to encrypt the key. The administrator will be able to: - Add a new master key to master key principal and optionally to the masterkey keytab stash. - Enable a new master key (make it the current master key used to protect newly created principals or principal rekeys). - List all master keys associated with the master key principal. - Delete a particular master key from the master key principal and optionally from the masterkey keytab stash. - Purge unused master keys (keys not used to protect any principal). Fundamentally the current implementation must be changed to support multiple master keys. And possession of any master key stored with the K/M principal allows access to all master keys. In addition, a principal's secret key may be encrypted by any of the master keys in use and the KDC retains in-use master keys in order to be be able to decrypt that principal's key. kdb5_util will be modified to support these new commands: add_mkey [-e etype] [-s] Adds a new master key to the K/M (master key) princi- pal. Existing master keys will remain. The -e etype option allows specification of the enctype of the new master key. The -s option stashes the new master key in a local stash file which will be created if it doesn't already exist. use_mkey mkeyVNO [time] Sets the activation time of the master key specified by mkeyVNO. Once a master key is active (i.e. its activa- tion time has been reached) it will then be used to encrypt principal keys either when the principal keys change, are newly created or when the update_princ_encryption command is run. If the time argument is provided then that will be the activation time otherwise the current time is used by default. The format of the optional time argument is that speci- fied in the Time Formats section of the kadmin man page. list_mkeys List all master keys from most recent to earliest in K/M principal. The output will show the KVNO, enctype and salt for each mkey similar to kadmin getprinc output. A * following an mkey denotes the currently active master key. purge_mkeys [-f] [-n] [-v] Delete master keys from the K/M principal that are not used to protect any principals. -f do not prompt user. -n do a dry run, shows master keys that would be purged, does not actually purge them. -v verbose output. update_princ_encryption [-f] [-n] [-v] [princ-pattern] Update all principal records (or only those matching the princ-pattern glob pattern) to re-encrypt the key data using the active database master key, if they are encrypted using older versions, and give a count at the end of the number of principals updated. If the -f option is not given, ask for confirmation before start- ing to make changes. The -v option causes each princi- pal processed (each one matching the pattern) to be listed, and an indication given as to whether it needed updating or not. The -n option causes the actions not to be taken, only the normal or verbose status messages displayed; this implies -f since no database changes will be performed and thus there's little reason to seek confirmation. The existing stash command will change from: stash [-f keyfile] Creates a stash file. If -f was not specified, the default stash file name is /var/krb5/.k5.realm. You will be prompted for the master database password. This command is useful when you want to generate the stash file from the password. to: stash [-f keyfile] Stores the master principal's keys in a stash file. The -f argument can be used to override the keyfile specified at startup. The stash command will retrieve the keys stored in the K/M master principal entry and store them in a stash file which will either be the default or that specified by the -f flag. DOCUMENTATION ------------- * Man page updates will be given for kdb5_util(1). * http://docs.sun.com the Kerberos chapter will also be updated. INTERFACE STABILITY AND RELEASE BINDINGS ---------------------------------------- Interface Stability Release Binding new kdb5_util args Volatile Micro/Patch