Administering the Kerberos Database

The Kerberos database is the backbone of Kerberos and must be maintained properly. This section provides some procedures on how to administer the Kerberos database, such as backing up and restoring the database, setting up incremental or parallel propagation, and administering the stash file. The steps to initially set up the database are in How to Manually Configure a Master KDC.

Backing Up and Propagating the Kerberos Database

Propagating the Kerberos database from the master KDC to the slave KDCs is one of the most important configuration tasks. If propagation doesn't happen often enough, the master KDC and the slave KDCs will lose synchronization. So, if the master KDC goes down, the slave KDCs will not have the most recent database information. Also, if a slave KDC has been configured as a master KDC for purposes of load balancing, the clients that use that slave KDC as a master KDC will not have the latest information. Therefore, you must make sure that propagation occurs often enough or else configure the servers for incremental propagation, based on how often you change the Kerberos database. Incremental propagation is preferred over manual propagation because there is more administrative overhead when you manually propagate the database. Also, there are inefficiencies when you do full propagation of the database.

When you configure the master KDC, you set up the kprop_script command in a cron job to automatically back up the Kerberos database to the /var/krb5/slave_datatrans dump file and propagate it to the slave KDCs. But, as with any file, the Kerberos database can become corrupted. If data corruption occurs on a slave KDC, you might never notice, because the next automatic propagation of the database installs a fresh copy. However, if corruption occurs on the master KDC, the corrupted database is propagated to all of the slave KDCs during the next propagation. And, the corrupted backup overwrites the previous uncorrupted backup file on the master KDC.

Because there is no “safe” backup copy in this scenario, you should also set up a cron job to periodically copy the slave_datatrans dump file to another location or to create another separate backup copy by using the dump command of kdb5_util. Then, if your database becomes corrupted, you can restore the most recent backup on the master KDC by using the load command of kdb5_util.

Another important note: Because the database dump file contains principal keys, you need to protect the file from being accessed by unauthorized users. By default, the database dump file has read and write permissions only as root. To protect against unauthorized access, use only the kprop command to propagate the database dump file, which encrypts the data that is being transferred. Also, kprop propagates the data only to the slave KDCs, which minimizes the chance of accidentally sending the database dump file to unauthorized hosts.

---

Caution - If the Kerberos database is updated after it has been propagated and if the database subsequently is corrupted before the next propagation, the KDC slaves will not contain the updates. The updates will be lost. For this reason, if you add significant updates to the Kerberos database before a regularly scheduled propagation, you should manually propagate the database to avoid data loss.

---

The kpropd.acl File

The kpropd.acl file on a slave KDC provides a list of host principal names, one name per line, that specifies the systems from which the KDC can receive an updated database through propagation. If the master KDC is used to propagate all the slave KDCs, the kpropd.acl file on each slave needs to contain only the host principal name of the master KDC.

However, the Kerberos installation and subsequent configuration steps in this book instruct you to add the same kpropd.acl file to the master KDC and the slave KDCs. This file contains all the KDC host principal names. This configuration enables you to propagate from any KDC, in case the propagating KDCs become temporarily unavailable. And, by keeping an identical copy on all KDCs, you make the configuration easy to maintain.

The kprop_script Command

The kprop_script command uses the kprop command to propagate the Kerberos database to other KDCs. If the kprop_script command is run on a slave KDC, it propagates the slave KDC's copy of the Kerberos database to other KDCs. The kprop_script accepts a list of host names for arguments, separated by spaces, which denote the KDCs to propagate.

When kprop_script is run, it creates a backup of the Kerberos database to the /var/krb5/slave_datatrans file and copies the file to the specified KDCs. The Kerberos database is locked until the propagation is finished.

How to Back Up the Kerberos Database

Before You Begin

You must assume the root role. For more information, see How to Use Your Assigned Administrative Rights.

• Back up the Kerberos database by using the dump command of the kdb5_util command.

  # /usr/sbin/kdb5_util dump [-verbose] [-d dbname] [filename [principals...]]

  -verbose

  Prints the name of each principal and policy that is being backed up.

  dbname

  Defines the name of the database to back up. Note that you can specify an absolute path for the file. If the -d option is not specified, the default database name is /var/krb5/principal.

  filename

  Defines the file that is used to back up the database. You can specify an absolute path for the file. If you don't specify a file, the database is dumped to standard output.

  principals

  Defines a list of one or more principals (separated by a space) to back up. You must use fully qualified principal names. If you don't specify any principals, the entire database is backed up.

Example 21-19 Backing Up the Kerberos Database

In the following example, the Kerberos database is backed up to a file called dumpfile. Because the -verbose option is specified, each principal is printed as it is backed up.

# kdb5_util dump -verbose dumpfile 
kadmin/kdc1.eng.example.com@ENG.EXAMPLE.COM 
krbtgt/ENG.EXAMPLE.COM@ENG.EXAMPLE.COM 
kadmin/history@ENG.EXAMPLE.COM 
pak/admin@ENG.EXAMPLE.COM 
pak@ENG.EXAMPLE.COM
changepw/kdc1.eng.example.com@ENG.EXAMPLE.COM

In the following example, the pak and pak/admin principals from the Kerberos database are backed up.

# kdb5_util dump -verbose dumpfile pak/admin@ENG.EXAMPLE.COM pak@ENG.EXAMPLE.COM
pak/admin@ENG.EXAMPLE.COM
pak@ENG.EXAMPLE.COM

How to Restore the Kerberos Database

Before You Begin

On the KDC master, you must assume the root role. For more information, see How to Use Your Assigned Administrative Rights.

1. On the master, stop the KDC daemons.

   kdc1 # svcadm disable network/security/krb5kdc
   kdc1 # svcadm disable network/security/kadmin

2. Restore the Kerberos database by using the load command of the kdb_util command.

   # /usr/sbin/kdb5_util load [-verbose] [-d dbname] [-update] [filename] 

   -verbose

   Prints the name of each principal and policy that is being restored.

   dbname

   Defines the name of the database to restore. Note you can specify an absolute path for the file. If the -d option is not specified, the default database name is /var/krb5/principal.

   -update

   Updates the existing database. Otherwise, a new database is created or the existing database is overwritten.

   filename

   Defines the file from which to restore the database. You can specify an absolute path for the file.

3. Start the KDC daemons.

   kdc1 # svcadm enable -r network/security/krb5kdc
   kdc1 # svcadm enable -r network/security/kadmin

Example 21-20 Restoring the Kerberos Database

In the following example, the database called database1 is restored into the current directory from the dumpfile file. Because the -update option isn't specified, a new database is created by the restore.

# kdb5_util load -d database1 dumpfile

How to Convert a Kerberos Database After a Server Upgrade

If your KDC database was created on a server running the Solaris 8 or Solaris 9 release, converting the database enables you to take advantage of the improved database format.

Before You Begin

Make sure that the database is using an older format.

On the KDC master, you must assume the root role. For more information, see How to Use Your Assigned Administrative Rights.

1. On the master, stop the KDC daemons.

   kdc1 # svcadm disable network/security/krb5kdc
   kdc1 # svcadm disable network/security/kadmin

2. Create a directory to store a temporary copy of the database.

   kdc1 # mkdir /var/krb5/tmp
   kdc1 # chmod 700 /var/krb5/tmp

3. Dump the KDC database.

   kdc1 # kdb5_util dump /var/krb5/tmp/prdb.txt

4. Save copies of the current database files.

   kdc1 # cd /var/krb5
   kdc1 # mv princ* tmp/

5. Load the database.

   kdc1 # kdb5_util load /var/krb5/tmp/prdb.txt

6. Start the KDC daemons.

   kdc1 # svcadm enable -r network/security/krb5kdc
   kdc1 # svcadm enable -r network/security/kadmin

How to Reconfigure a Master KDC to Use Incremental Propagation

The steps in this procedure can be used to reconfigure an existing master KDC to use incremental propagation. In this procedure, the following configuration parameters are used:

• Realm name = EXAMPLE.COM

• DNS domain name = example.com

• Master KDC = kdc1.example.com

• Slave KDC = kdc2.example.com

• admin principal = kws/admin

Before You Begin

You must assume the root role. For more information, see How to Use Your Assigned Administrative Rights.

1. Add entries to kdc.conf.

   You need to enable incremental propagation and select the number of updates the KDC master keeps in the log. See the kdc.conf(4) man page for more information.

   kdc1 # cat /etc/krb5/kdc.conf
   [kdcdefaults]
           kdc_ports = 88,750
   
   [realms]
           EXAMPLE.COM= {
                   profile = /etc/krb5/krb5.conf
                   database_name = /var/krb5/principal
                   acl_file = /etc/krb5/kadm5.acl
                   kadmind_port = 749
                   max_life = 8h 0m 0s
                   max_renewable_life = 7d 0h 0m 0s
                   sunw_dbprop_enable = true
                   sunw_dbprop_master_ulogsize = 1000
           }

2. Create the kiprop principal.

   The kiprop principal is used to authenticate the master KDC server and to authorize updates from the master KDC.

   kdc1 # /usr/sbin/kadmin -p kws/admin
   Enter password: <Type kws/admin password>
   kadmin: addprinc -randkey kiprop/kdc1.example.com
   Principal "kiprop/kdc1.example.com@EXAMPLE.COM" created.
   kadmin: addprinc -randkey kiprop/kdc2.example.com
   Principal "kiprop/kdc2.example.com@EXAMPLE.COM" created.
   kadmin:

3. On the master KDC, add a kiprop entry to kadm5.acl

   This entry allows the master KDC to receive requests for incremental propagation from the kdc2 server.

   kdc1 # cat /etc/krb5/kadm5.acl
   */admin@EXAMPLE.COM *
   kiprop/kdc2.example.com@EXAMPLE.COM p

4. Comment out the kprop line in the root crontab file.

   This step prevents the master KDC from propagating its copy of the KDC database.

   kdc1 # crontab -e
   #ident  "@(#)root       1.20    01/11/06 SMI"
   #
   # The root crontab should be used to perform accounting data collection.
   #
   # The rtc command is run to adjust the real time clock if and when
   # daylight savings time changes.
   #
   10 3 * * * /usr/sbin/logadm
   15 3 * * 0 /usr/lib/fs/nfs/nfsfind
   1 2 * * * [ -x /usr/sbin/rtc ] && /usr/sbin/rtc -c > /dev/null 2>&1
   30 3 * * * [ -x /usr/lib/gss/gsscred_clean ] && /usr/lib/gss/gsscred_clean
   #10 3 * * * /usr/lib/krb5kprop_script kdc2.example.sun.com #SUNWkr5ma

5. Restart kadmind.

   kdc1 # svcadm restart network/security/kadmin

6. Reconfigure all slave KDC servers that use incremental propagation.

   See How to Reconfigure a Slave KDC to Use Incremental Propagation for complete instructions.

How to Reconfigure a Slave KDC to Use Incremental Propagation

Before You Begin

You must assume the root role. For more information, see How to Use Your Assigned Administrative Rights.

1. Add entries to kdc.conf.

   The first new entry enables incremental propagation. The second new entry sets the poll time to two minutes.

   kdc2 # cat /etc/krb5/kdc.conf
   [kdcdefaults]
           kdc_ports = 88,750
   
   [realms]
           EXAMPLE.COM= {
                   profile = /etc/krb5/krb5.conf
                   database_name = /var/krb5/principal
                   acl_file = /etc/krb5/kadm5.acl
                   kadmind_port = 749
                   max_life = 8h 0m 0s
                   max_renewable_life = 7d 0h 0m 0s
                   sunw_dbprop_enable = true
                   sunw_dbprop_slave_poll = 2m
           }

2. Add the kiprop principal to the krb5.keytab file.

   kdc2 # /usr/sbin/kadmin -p kws/admin
   Enter password: <Type kws/admin password>
   kadmin: ktadd kiprop/kdc2.example.com
   Entry for principal kiprop/kdc2.example.com with kvno 3, encryption type AES-256 CTS mode
             with 96-bit SHA-1 HMAC added to keytab WRFILE:/etc/krb5/krb5.keytab.
   Entry for principal kiprop/kdc2.example.com with kvno 3, encryption type AES-128 CTS mode
             with 96-bit SHA-1 HMAC added to keytab WRFILE:/etc/krb5/krb5.keytab.
   Entry for principal kiprop/kdc2.example.com with kvno 3, encryption type Triple DES cbc
             mode with HMAC/sha1 added to keytab WRFILE:/etc/krb5/krb5.keytab.
   Entry for principal kiprop/kdc2.example.com with kvno 3, encryption type ArcFour
             with HMAC/md5 added to keytab WRFILE:/etc/krb5/krb5.keytab.
   Entry for principal kiprop/kdc2.example.com with kvno 3, encryption type DES cbc mode
             with RSA-MD5 added to keytab WRFILE:/etc/krb5/krb5.keytab.
   kadmin: quit

3. Restart kpropd.

   kdc2 # svcadm restart network/security/krb5_prop

How to Configure a Slave KDC to Use Full Propagation

This procedure shows how to reconfigure a slave KDC server that is running the Solaris 10 release to use full propagation. Normally, the procedure would only be used if the master KDC server is running either the Solaris 9 release or an earlier release. In this case, the master KDC server cannot support incremental propagation, so the slave must be configured to allow propagation to work.

In this procedure, a slave KDC named kdc3 is configured. This procedure uses the following configuration parameters:

• Realm name = EXAMPLE.COM

• DNS domain name = example.com

• Master KDC = kdc1.example.com

• Slave KDC = kdc2.example.com and kdc3.example.com

• admin principal = kws/admin

• Online help URL = http://docs.oracle.com/cd/E23824_01/html/821-1456/aadmin-23.html

  ---

  Note - Adjust the URL to point to the section, as described in Online Help URL in the Graphical Kerberos Administration Tool.

  ---

Before You Begin

The master KDC must be configured. For specific instructions if this slave is to be swappable, see Swapping a Master KDC and a Slave KDC.

On the master KDC, you must assume the root role. For more information, see How to Use Your Assigned Administrative Rights.

1. On the master KDC, start kadmin.

   You must log in with one of the admin principal names that you created when you configured the master KDC.

   kdc1 # /usr/sbin/kadmin -p kws/admin
   Enter password: <Type kws/admin password>
   kadmin: 

   1. On the master KDC, add slave host principals to the database, if not already done.

      For the slave to function, it must have a host principal. Note that when the principal instance is a host name, the FQDN must be specified in lowercase letters, regardless of the case of the domain name in the name service.

      kadmin: addprinc -randkey host/kdc3.example.com
      Principal "host/kdc3@EXAMPLE.COM" created.
      kadmin: 

   2. Quit kadmin.

      kadmin: quit

2. On the master KDC, edit the Kerberos configuration file (krb5.conf).

   You need to add an entry for each slave. See the krb5.conf(4) man page for a full description of this file.

   kdc1 # cat /etc/krb5/krb5.conf
    .
    .
   [realms]
                   EXAMPLE.COM = {
                   kdc = kdc1.example.com
                   kdc = kdc2.example.com
                   kdc = kdc3.example.com
                   admin_server = kdc1.example.com
           }

3. On the master KDC, add an entry for the master KDC and each slave KDC into the kpropd.acl file.

   See the kprop(1M) man page for a full description of this file.

   kdc1 # cat /etc/krb5/kpropd.acl
   host/kdc1.example.com@EXAMPLE.COM
   host/kdc2.example.com@EXAMPLE.COM
   host/kdc3.example.com@EXAMPLE.COM

4. On all slave KDCs, copy the KDC administration files from the master KDC server.

   This step needs to be followed on all slave KDCs, because the master KDC server has updated information that each KDC server needs. You can use ftp or a similar transfer mechanism to grab copies of the following files from the master KDC:

   • /etc/krb5/krb5.conf

   • /etc/krb5/kdc.conf

   • /etc/krb5/kpropd.acl

5. On all slave KDCs, make sure that the Kerberos access control list file, kadm5.acl, is not populated.

   An unmodified kadm5.acl file would look like:

   kdc2 # cat /etc/krb5/kadm5.acl
   */admin@___default_realm___ *

   If the file has kiprop entries, remove them.

6. On the new slave, start the kadmin command.

   You must log in with one of the admin principal names that you created when you configured the master KDC.

   kdc2 # /usr/sbin/kadmin -p kws/admin
   Enter password: <Type kws/admin password>
   kadmin: 

   1. Add the slave's host principal to the slave's keytab file by using kadmin.

      This entry allows kprop and other Kerberized applications to function. Note that when the principal instance is a host name, the FQDN must be specified in lowercase letters, regardless of the case of the domain name in the name service.

      kadmin: ktadd host/kdc3.example.com
      Entry for principal host/kdc3.example.com with kvno 3, encryption type AES-256 CTS mode
                with 96-bit SHA-1 HMAC added to keytab WRFILE:/etc/krb5/krb5.keytab.
      Entry for principal host/kdc3.example.com with kvno 3, encryption type AES-128 CTS mode
                with 96-bit SHA-1 HMAC added to keytab WRFILE:/etc/krb5/krb5.keytab.
      Entry for principal host/kdc3.example.com with kvno 3, encryption type Triple DES cbc
                mode with HMAC/sha1 added to keytab WRFILE:/etc/krb5/krb5.keytab.
      Entry for principal host/kdc3.example.com with kvno 3, encryption type ArcFour
                with HMAC/md5 added to keytab WRFILE:/etc/krb5/krb5.keytab.
      Entry for principal host/kdc3.example.com with kvno 3, encryption type DES cbc mode
                with RSA-MD5 added to keytab WRFILE:/etc/krb5/krb5.keytab.
      kadmin: 

   2. Quit kadmin.

      kadmin: quit

7. On the master KDC, add the slave KDC name to the cron job, which automatically runs the backups, by running crontab -e.

   Add the name of each slave KDC server at the end of the kprop_script line.

   10 3 * * * /usr/lib/krb5/kprop_script kdc2.example.com kdc3.example.com

   You might also want to change the time of the backups. This entry starts the backup process every day at 3:10 AM.

8. On the new slave, start the Kerberos propagation daemon.

   kdc3 # svcadm enable network/security/krb5_prop

9. On the master KDC, back up and propagate the database by using kprop_script.

   If a backup copy of the database is already available, it is not necessary to complete another backup. See How to Manually Propagate the Kerberos Database to the Slave KDCs for further instructions.

   kdc1 # /usr/lib/krb5/kprop_script kdc3.example.com
   Database propagation to kdc3.example.com: SUCCEEDED

10. On the new slave, create a stash file by using kdb5_util.

    kdc3 # /usr/sbin/kdb5_util stash
    kdb5_util: Cannot find/read stored master key while reading master key
    kdb5_util: Warning: proceeding without master key
    
    Enter KDC database master key: <Type the key>

11. (Optional) On the new slave KDC, synchronize the master KDCs clock by using NTP or another clock synchronization mechanism.

    Installing and using the Network Time Protocol (NTP) is not required. However, every clock must be within the default time that is defined in the libdefaults section of the krb5.conf file for authentication to succeed. See Synchronizing Clocks Between KDCs and Kerberos Clients for information about NTP.

12. On the new slave, start the KDC daemon (krb5kdc).

    kdc3 # svcadm enable network/security/krb5kdc

How to Verify That the KDC Servers Are Synchronized

If incremental propagation has been configured, this procedure ensures that the information on the slave KDC has been updated.

Before You Begin

You must assume the root role. For more information, see How to Use Your Assigned Administrative Rights.

1. On the KDC master server, run the kproplog command.

   kdc1 # /usr/sbin/kproplog -h

2. On a KDC slave server, run the kproplog command.

   kdc2 # /usr/sbin/kproplog -h

3. Check that the last serial # and the last timestamp values match.

Example 21-21 Verifying That the KDC Servers Are Synchronized

The following is a sample of results from running the kproplog command on the master KDC server.

kdc1 # /usr/sbin/kproplog -h

Kerberos update log (/var/krb5/principal.ulog)
Update log dump:
    Log version #: 1
    Log state: Stable
    Entry block size: 2048
    Number of entries: 2500
    First serial #: 137966
    Last serial #: 140465
    First time stamp: Fri Nov 28 00:59:27 2004
    Last time stamp: Fri Nov 28 01:06:13 2004

The following is a sample of results from running the kproplog command on a slave KDC server.

kdc2 # /usr/sbin/kproplog -h

Kerberos update log (/var/krb5/principal.ulog)
Update log dump:
    Log version #: 1
    Log state: Stable
    Entry block size: 2048
    Number of entries: 0
    First serial #: None
    Last serial #: 140465
    First time stamp: None
    Last time stamp: Fri Nov 28 01:06:13 2004

Notice that the values for the last serial number and the last timestamp are identical, which indicates that the slave is synchronized with the master KDC server.

In the slave KDC server output, notice that no update entries exist in the slave KDC server's update log. No entries exist because the slave KDC server does not keep a set of updates, unlike the master KDC server. Also, the KDC slave server does not include information on the first serial number or the first timestamp because this is not relevant information.

How to Manually Propagate the Kerberos Database to the Slave KDCs

This procedure shows you how to propagate the Kerberos database by using the kprop command. Use this procedure if you need to synchronize a slave KDC with the master KDC outside the periodic cron job. Unlike the kprop_script, you can use kprop to propagate just the current database backup without first making a new backup of the Kerberos database.

Before You Begin

You must assume the root role. For more information, see How to Use Your Assigned Administrative Rights.

1. (Optional) Back up the database by using the kdb5_util command.

   # /usr/sbin/kdb5_util dump /var/krb5/slave_datatrans

2. Propagate the database to a slave KDC by using the kprop command.

   # /usr/lib/krb5/kprop -f /var/krb5/slave_datatrans slave-KDC

Example 21-22 Manually Propagating the Kerberos Database to the Slave KDCs Using kprop_script

If you want to back up the database and propagate it to a slave KDC outside the periodic cron job, you can also use the kprop_script command as follows:

# /usr/lib/krb5/kprop_script slave-KDC

Setting Up Parallel Propagation

In most cases, the master KDC is used exclusively to propagate its Kerberos database to the slave KDCs. However, if your site has many slave KDCs, you might consider load-sharing the propagation process, known as parallel propagation.

Parallel propagation allows specific slave KDCs to share the propagation duties with the master KDC. This sharing of duties enables the propagation to be done faster and to lighten the work for the master KDC.

For example, say your site has one master KDC and six slave KDCs (shown in Figure 21-2), where slave-1 through slave-3 consist of one logical grouping and slave-4 through slave-6 consist of another logical grouping. To set up parallel propagation, you could have the master KDC propagate the database to slave-1 and slave-4. In turn, those KDC slaves could propagate the database to the KDC slaves in their group.

Figure 21-2 Example of Parallel Propagation Configuration

Configuration Steps for Setting Up Parallel Propagation

The following is not a detailed step-by-step procedure, but a high-level list of configuration steps to enable parallel propagation. These steps involve the following:

1. On the master KDC, changing the kprop_script entry in its cron job to include arguments for only the KDC slaves that will perform the succeeding propagation (the propagation slaves).

2. On each propagation slave, adding a kprop_script entry to its cron job, which must include arguments for the slaves to propagate. To successfully propagate in parallel, the cron job should be set up to run after the propagation slave is itself propagated with the new Kerberos database.

   ---

   Note - How long it will take for a propagation slave to be propagated depends on factors such as network bandwidth and the size of the Kerberos database.

   ---

3. On each slave KDC, setting up the appropriate permissions to be propagated. This step is done by adding the host principal name of its propagating KDC to its kpropd.acl file.

Example 21-23 Setting Up Parallel Propagation

Using the example in Figure 21-2, the master KDC's kprop_script entry would look similar to the following:

0 3 * * * /usr/lib/krb5/kprop_script slave-1.example.com slave-4.example.com

The slave-1's kprop_script entry would look similar to the following:

0 4 * * * /usr/lib/krb5/kprop_script slave-2.example.com slave-3.example.com

Note that the propagation on the slave starts an hour after it is propagated by the master.

The kpropd.acl file on the propagation slaves would contain the following entry:

host/master.example.com@EXAMPLE.COM

The kpropd.acl file on the KDC slaves being propagated by slave-1 would contain the following entry:

host/slave-1.example.com@EXAMPLE.COM

Administering the Stash File

The stash file contains the master key for the Kerberos database, which is automatically created when you create a Kerberos database. If the stash file gets corrupted, you can use the stash command of the kdb5_util utility to replace the corrupted file. The only time you should need to remove a stash file is after removing the Kerberos database with the destroy command of kdb5_util. Because the stash file is not automatically removed with the database, you have to remove the stash file to finish the cleanup.

How to Remove a Stash File

Before You Begin

You must assume the root role. For more information, see How to Use Your Assigned Administrative Rights.

• Remove the stash file.

  # rm stash-file

  Where stash-file is the path to the stash file. By default, the stash file is located at /var/krb5/.k5.realm.

  ---

  Note - If you need to re-create the stash file, you can use the -f option of the kdb5_util command.

  ---

How to Employ a New Master Key

Before You Begin

You must assume the root role. For more information, see How to Use Your Assigned Administrative Rights.

1. Create a new master key.

   This command adds a new, randomly generated master key. The -s option requests that the new master key be stored in the default keytab.

   # kdb5_util add_mkey -s
   
   Creating new master key for master key principal 'K/M@EXAMPLE.COM'
   You will be prompted for a new database Master Password.
   It is important that you NOT FORGET this password. 
   Enter KDC database master key: <Type the password>
   Re-enter KDC database master key to verify: <Type it again>

2. Verify that the new master key exists.

   # kdb5_util list_mkeys
   Master keys for Principal: K/M@EXAMPLE.COM
   KNVO: 2, Enctype: AES-128 CTS mode with 96-bit SHA-1 HMAC, No activate time set
   KNVO: 1, Enctype: DES cbc mode with RSA-MD5, Active on: Wed Dec 31 18:00:00 CST 2001 *

   The asterisk in this output identifies the currently active master key.

3. Set a time for the newly created master key to become active.

   # date
   Fri Jul 1 17:57:00 CDT 2011
   # kdb5_util use_mkey 2 'now+2days'
   # kdb5_util list_mkeys
   Master keys for Principal: K/M@EXAMPLE.COM
   KNVO: 2, Enctype: AES-128 CTS mode with 96-bit SHA-1 HMAC, Active on: Sun Jul 03 17:57:15 CDT 2011
   KNVO: 1, Enctype: DES cbc mode with RSA-MD5, Active on: Wed Dec 31 18:00:00 CST 2001 *

   In this example, the date is set to two days in the future to allow time for the new master key to propagate to all of the KDCs. Adjust the date as appropriate for your environment.

4. (Optional) After creating a new principal, verify that the new master key is being used.

   # kadmin.local -q 'getprinc jimf' |egrep 'Principal|MKey'
   Authenticating as principal root/admin@EXAMPLE.COM with password.
   Principal: jimf@EXAMPLE.COM
   MKey: vno 2

   In this example, MKey: vno 2 indicates that the principal's secret key is protected by newly created master key, 2.

5. Re-encrypt the user principal secret keys with the new master key.

   If you add a pattern argument to the end of the command, the principals that match the pattern will be updated. Add the -n option to this command syntax to identify which principals will be updated.

   # kdb5_util update_princ_encryption -f -v
   Principals whose keys WOULD BE re-encrypted to master key vno 2:
   updating: host/kdc1.example.com@EXAMPLE.COM
   skipping:   jimf@EXAMPLE.COM
   updating: kadmin/changepw@EXAMPLE.COM
   updating: kadmin/history@EXAMPLE.COM
   updating: kdc/admin@EXAMPLE.COM
   updating: host/kdc2.example.com@EXAMPLE.COM
   6 principals processed: 5 updated, 1 already current

6. Purge the old master key.

   After a master key is no longer used to protect any principal secret keys, it can be purged from the master key principal. This command will not purge the key if the key is still being used by any principals. Add the -n option to this command to verify that the correct master key will be purged.

   # kdb5_util purge_mkeys -f -v
   Purging the follwing master key(s) from K/M@EXAMPLE.COM:
   KNVO: 1
   1 key(s) purged.

7. Verify that the old master key has been purged.

   # kdb5_util list_mkeys
   Master keys for Principal: K/M@EXAMPLE.COM
   KNVO: 2, Enctype: AES-128 CTS mode with 96-bit SHA-1 HMAC, Active on: Sun Jul 03 17:57:15 CDT 2011 *

8. Update the stash file.

   # kdb5_util stash
   Using existing stashed keys to update stash file.

9. Verify that the stash file has been updated.

   # klist -kt /var/krb5/.k5.EXAMPLE.COM
   Keytab name: FILE:.k5.EXAMPLE.COM
   KVNO Timestamp              Principal
   ---- ---------------- ---------------------------------------------------------
      2 05/07/2011 15:08 K/M@EXAMPLE.COM