Database administration

A Kerberos database contains all of a realm’s Kerberos principals, their passwords, and other administrative information about each principal. For the most part, you will use the kdb5_util program to manipulate the Kerberos database as a whole, and the kadmin program to make changes to the entries in the database. (One notable exception is that users will use the kpasswd program to change their own passwords.) The kadmin program has its own command-line interface, to which you type the database administrating commands.

kdb5_util provides a means to create, delete, load, or dump a Kerberos database. It also contains commands to roll over the database master key, and to stash a copy of the key so that the kadmind and krb5kdc daemons can use the database without manual input.

kadmin provides for the maintenance of Kerberos principals, password policies, and service key tables (keytabs). Normally it operates as a network client using Kerberos authentication to communicate with kadmind, but there is also a variant, named kadmin.local, which directly accesses the Kerberos database on the local filesystem (or through LDAP). kadmin.local is necessary to set up enough of the database to be able to use the remote version.

kadmin can authenticate to the admin server using the service principal kadmin/admin or kadmin/HOST (where HOST is the hostname of the admin server). If the credentials cache contains a ticket for either service principal and the -c ccache option is specified, that ticket is used to authenticate to KADM5. Otherwise, the -p and -k options are used to specify the client Kerberos principal name used to authenticate. Once kadmin has determined the principal name, it requests a kadmin/admin Kerberos service ticket from the KDC, and uses that service ticket to authenticate to KADM5.

See kadmin for the available kadmin and kadmin.local commands and options.

Principals

Each entry in the Kerberos database contains a Kerberos principal and the attributes and policies associated with that principal.

To add a principal to the database, use the kadmin add_principal command. User principals should usually be created with the +requires_preauth -allow_svr options to help mitigate dictionary attacks (see Addressing dictionary attack risks):

kadmin: addprinc +requires_preauth -allow_svr alice
Enter password for principal "alice@KRBTEST.COM":
Re-enter password for principal "alice@KRBTEST.COM":

User principals which will authenticate with PKINIT configuration should instead by created with the -nokey option:

kadmin: addprinc -nokey alice

Service principals can be created with the -nokey option; long-term keys will be added when a keytab is generated:

kadmin: addprinc -nokey host/foo.mit.edu
kadmin: ktadd -k foo.keytab host/foo.mit.edu
Entry for principal host/foo.mit.edu with kvno 1, encryption type aes256-cts-hmac-sha1-96 added to keytab WRFILE:foo.keytab.
Entry for principal host/foo.mit.edu with kvno 1, encryption type aes128-cts-hmac-sha1-96 added to keytab WRFILE:foo.keytab.

To modify attributes of an existing principal, use the kadmin modify_principal command:

kadmin: modprinc -expire tomorrow alice
Principal "alice@KRBTEST.COM" modified.

To delete a principal, use the kadmin delete_principal command:

kadmin: delprinc alice
Are you sure you want to delete the principal "alice@KRBTEST.COM"? (yes/no): yes
Principal "alice@KRBTEST.COM" deleted.
Make sure that you have removed this principal from all ACLs before reusing.

To change a principal’s password, use the kadmin change_password command. Password changes made through kadmin are subject to the same password policies as would apply to password changes made through kpasswd.

To view the attributes of a principal, use the kadmin` get_principal command.

To generate a listing of principals, use the kadmin list_principals command.

Policies

A policy is a set of rules governing passwords. Policies can dictate minimum and maximum password lifetimes, minimum number of characters and character classes a password must contain, and the number of old passwords kept in the database.

To add a new policy, use the kadmin add_policy command:

kadmin: addpol -maxlife "1 year" -history 3 stduser

To modify attributes of a principal, use the kadmin modify_policy command. To delete a policy, use the kadmin delete_policy command.

To associate a policy with a principal, use the kadmin modify_principal command with the -policy option:

kadmin: modprinc -policy stduser alice Principal “alice@KRBTEST.COM” modified.

A principal entry may be associated with a nonexistent policy, either because the policy did not exist at the time of associated or was deleted afterwards. kadmin will warn when associated a principal with a nonexistent policy, and will annotate the policy name with “[does not exist]” in the get_principal output.

Updating the history key

If a policy specifies a number of old keys kept of two or more, the stored old keys are encrypted in a history key, which is found in the key data of the kadmin/history principal.

Currently there is no support for proper rollover of the history key, but you can change the history key (for example, to use a better encryption type) at the cost of invalidating currently stored old keys. To change the history key, run:

kadmin: change_password -randkey kadmin/history

This command will fail if you specify the -keepold flag. Only one new history key will be created, even if you specify multiple key/salt combinations.

In the future, we plan to migrate towards encrypting old keys in the master key instead of the history key, and implementing proper rollover support for stored old keys.

Privileges

Administrative privileges for the Kerberos database are stored in the file kadm5.acl.

Note

A common use of an admin instance is so you can grant separate permissions (such as administrator access to the Kerberos database) to a separate Kerberos principal. For example, the user joeadmin might have a principal for his administrative use, called joeadmin/admin. This way, joeadmin would obtain joeadmin/admin tickets only when he actually needs to use those permissions.

Operations on the Kerberos database

The kdb5_util command is the primary tool for administrating the Kerberos database when using the DB2 or LMDB modules (see Database types). Creating a database is described in Create the KDC database.

To create a stash file using the master password (because the database was not created with one using the create -s flag, or after restoring from a backup which did not contain the stash file), use the kdb5_util stash command:

$ 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 KDC database master password.

To destroy a database, use the kdb5_util destroy command:

$ kdb5_util destroy
Deleting KDC database stored in '/var/krb5kdc/principal', are you sure?
(type 'yes' to confirm)? yes
OK, deleting database '/var/krb5kdc/principal'...
** Database '/var/krb5kdc/principal' destroyed.

Dumping and loading a Kerberos database

To dump a Kerberos database into a text file for backup or transfer purposes, use the kdb5_util dump command on one of the KDCs:

$ kdb5_util dump dumpfile

$ kbd5_util dump -verbose dumpfile
kadmin/admin@ATHENA.MIT.EDU
krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU
kadmin/history@ATHENA.MIT.EDU
K/M@ATHENA.MIT.EDU
kadmin/changepw@ATHENA.MIT.EDU

You may specify which principals to dump, using full principal names including realm:

$ kdb5_util dump -verbose someprincs K/M@ATHENA.MIT.EDU kadmin/admin@ATHENA.MIT.EDU
kadmin/admin@ATHENA.MIT.EDU
K/M@ATHENA.MIT.EDU

To restore a Kerberos database dump from a file, use the kdb5_util load command:

$ kdb5_util load dumpfile

To update an existing database with a partial dump file containing only some principals, use the -update flag:

$ kdb5_util load -update someprincs

Note

If the database file exists, and the -update flag was not given, kdb5_util will overwrite the existing database.

Updating the master key

Starting with release 1.7, kdb5_util allows the master key to be changed using a rollover process, with minimal loss of availability. To roll over the master key, follow these steps:

1. On the primary KDC, run kdb5_util list_mkeys to view the current master key version number (KVNO). If you have never rolled over the master key before, this will likely be version 1:

   $ kdb5_util list_mkeys
   Master keys for Principal: K/M@KRBTEST.COM
   KVNO: 1, Enctype: aes256-cts-hmac-sha384-192, Active on: Thu Jan 01 00:00:00 UTC 1970 *
   

2. On the primary KDC, run kdb5_util use_mkey 1 to ensure that a master key activation list is present in the database. This step is unnecessary in release 1.11.4 or later, or if the database was initially created with release 1.7 or later.

3. On the primary KDC, run kdb5_util add_mkey -s to create a new master key and write it to the stash file. Enter a secure password when prompted. If this is the first time you are changing the master key, the new key will have version 2. The new master key will not be used until you make it active.

4. Propagate the database to all replica KDCs, either manually or by waiting until the next scheduled propagation. If you do not have any replica KDCs, you can skip this and the next step.

5. On each replica KDC, run kdb5_util list_mkeys to verify that the new master key is present, and then kdb5_util stash to write the new master key to the replica KDC’s stash file.

6. On the primary KDC, run kdb5_util use_mkey 2 to begin using the new master key. Replace 2 with the version of the new master key, as appropriate. You can optionally specify a date for the new master key to become active; by default, it will become active immediately. Prior to release 1.12, kadmind must be restarted for this change to take full effect.

7. On the primary KDC, run kdb5_util update_princ_encryption. This command will iterate over the database and re-encrypt all keys in the new master key. If the database is large and uses DB2, the primary KDC will become unavailable while this command runs, but clients should fail over to replica KDCs (if any are present) during this time period. In release 1.13 and later, you can instead run kdb5_util -x unlockiter update_princ_encryption to use unlocked iteration; this variant will take longer, but will keep the database available to the KDC and kadmind while it runs.

8. Wait until the above changes have propagated to all replica KDCs and until all running KDC and kadmind processes have serviced requests using updated principal entries.

9. On the primary KDC, run kdb5_util purge_mkeys to clean up the old master key.

Operations on the LDAP database

The kdb5_ldap_util command is the primary tool for administrating the Kerberos database when using the LDAP module. Creating an LDAP Kerberos database is describe in Configuring Kerberos with OpenLDAP back-end.

To view a list of realms in the LDAP database, use the kdb5_ldap_util list command:

$ kdb5_ldap_util list
KRBTEST.COM

To modify the attributes of a realm, use the kdb5_ldap_util modify command. For example, to change the default realm’s maximum ticket life:

$ kdb5_ldap_util modify -maxtktlife "10 hours"

To display the attributes of a realm, use the kdb5_ldap_util view command:

$ kdb5_ldap_util view
               Realm Name: KRBTEST.COM
      Maximum Ticket Life: 0 days 00:10:00

To remove a realm from the LDAP database, destroying its contents, use the kdb5_ldap_util destroy command:

$ kdb5_ldap_util destroy
Deleting KDC database of 'KRBTEST.COM', are you sure?
(type 'yes' to confirm)? yes
OK, deleting database of 'KRBTEST.COM'...
** Database of 'KRBTEST.COM' destroyed.

Ticket Policy operations

Unlike the DB2 and LMDB modules, the LDAP module supports ticket policy objects, which can be associated with principals to restrict maximum ticket lifetimes and set mandatory principal flags. Ticket policy objects are distinct from the password policies described earlier on this page, and are chiefly managed through kdb5_ldap_util rather than kadmin. To create a new ticket policy, use the kdb5_ldap_util create_policy command:

$ kdb5_ldap_util create_policy -maxrenewlife "2 days" users

To associate a ticket policy with a principal, use the kadmin modify_principal (or add_principal) command with the -x tktpolicy=policy option:

$ kadmin.local modprinc -x tktpolicy=users alice

To remove a ticket policy reference from a principal, use the same command with an empty policy:

$ kadmin.local modprinc -x tktpolicy= alice

To list the existing ticket policy objects, use the kdb5_ldap_util list_policy command:

$ kdb5_ldap_util list_policy
users

To modify the attributes of a ticket policy object, use the kdb5_ldap_util modify_policy command:

$ kdb5_ldap_util modify_policy -allow_svr +requires_preauth users

To view the attributes of a ticket policy object, use the kdb5_ldap_util view_policy command:

$ kdb5_ldap_util view_policy users
            Ticket policy: users
   Maximum renewable life: 2 days 00:00:00
             Ticket flags: REQUIRES_PRE_AUTH DISALLOW_SVR

To destroy an ticket policy object, use the kdb5_ldap_util destroy_policy command:

$ kdb5_ldap_util destroy_policy users
This will delete the policy object 'users', are you sure?
(type 'yes' to confirm)? yes
** policy object 'users' deleted.

Cross-realm authentication

In order for a KDC in one realm to authenticate Kerberos users in a different realm, it must share a key with the KDC in the other realm. In both databases, there must be krbtgt service principals for both realms. For example, if you need to do cross-realm authentication between the realms ATHENA.MIT.EDU and EXAMPLE.COM, you would need to add the principals krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU and krbtgt/ATHENA.MIT.EDU@EXAMPLE.COM to both databases. These principals must all have the same passwords, key version numbers, and encryption types; this may require explicitly setting the key version number with the -kvno option.

In the ATHENA.MIT.EDU and EXAMPLE.COM cross-realm case, the administrators would run the following commands on the KDCs in both realms:

shell%: kadmin.local -e "aes256-cts:normal"
kadmin: addprinc -requires_preauth krbtgt/ATHENA.MIT.EDU@EXAMPLE.COM
Enter password for principal krbtgt/ATHENA.MIT.EDU@EXAMPLE.COM:
Re-enter password for principal krbtgt/ATHENA.MIT.EDU@EXAMPLE.COM:
kadmin: addprinc -requires_preauth krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU
Enter password for principal krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU:
Enter password for principal krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU:
kadmin:

Note

Even if most principals in a realm are generally created with the requires_preauth flag enabled, this flag is not desirable on cross-realm authentication keys because doing so makes it impossible to disable preauthentication on a service-by-service basis. Disabling it as in the example above is recommended.

Note

It is very important that these principals have good passwords. MIT recommends that TGT principal passwords be at least 26 characters of random ASCII text.

Changing the krbtgt key

A Kerberos Ticket Granting Ticket (TGT) is a service ticket for the principal krbtgt/REALM. The key for this principal is created when the Kerberos database is initialized and need not be changed. However, it will only have the encryption types supported by the KDC at the time of the initial database creation. To allow use of newer encryption types for the TGT, this key has to be changed.

Changing this key using the normal kadmin change_password command would invalidate any previously issued TGTs. Therefore, when changing this key, normally one should use the -keepold flag to change_password to retain the previous key in the database as well as the new key. For example:

kadmin: change_password -randkey -keepold krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU

Warning

After issuing this command, the old key is still valid and is still vulnerable to (for instance) brute force attacks. To completely retire an old key or encryption type, run the kadmin purgekeys command to delete keys with older kvnos, ideally first making sure that all tickets issued with the old keys have expired.

Only the first krbtgt key of the newest key version is used to encrypt ticket-granting tickets. However, the set of encryption types present in the krbtgt keys is used by default to determine the session key types supported by the krbtgt service (see Session key selection). Because non-MIT Kerberos clients sometimes send a limited set of encryption types when making AS requests, it can be important for the krbtgt service to support multiple encryption types. This can be accomplished by giving the krbtgt principal multiple keys, which is usually as simple as not specifying any -e option when changing the krbtgt key, or by setting the session_enctypes string attribute on the krbtgt principal (see set_string).

Due to a bug in releases 1.8 through 1.13, renewed and forwarded tickets may not work if the original ticket was obtained prior to a krbtgt key change and the modified ticket is obtained afterwards. Upgrading the KDC to release 1.14 or later will correct this bug.

Incremental database propagation

Overview

At some very large sites, dumping and transmitting the database can take more time than is desirable for changes to propagate from the primary KDC to the replica KDCs. The incremental propagation support added in the 1.7 release is intended to address this.

With incremental propagation enabled, all programs on the primary KDC that change the database also write information about the changes to an “update log” file, maintained as a circular buffer of a certain size. A process on each replica KDC connects to a service on the primary KDC (currently implemented in the kadmind server) and periodically requests the changes that have been made since the last check. By default, this check is done every two minutes.

Incremental propagation uses the following entries in the per-realm data in the KDC config file (See kdc.conf):

iprop_enable	boolean	If true, then incremental propagation is enabled, and (as noted below) normal kprop propagation is disabled. The default is false.
iprop_master_ulogsize	integer	Indicates the number of entries that should be retained in the update log. The default is 1000; the maximum number is 2500.
iprop_replica_poll	time interval	Indicates how often the replica should poll the primary KDC for changes to the database. The default is two minutes.
iprop_port	integer	Specifies the port number to be used for incremental propagation. This is required in both primary and replica configuration files.
iprop_resync_timeout	integer	Specifies the number of seconds to wait for a full propagation to complete. This is optional on replica configurations. Defaults to 300 seconds (5 minutes).
iprop_logfile	file name	Specifies where the update log file for the realm database is to be stored. The default is to use the database_name entry from the realms section of the config file kdc.conf, with .ulog appended. (NOTE: If database_name isn’t specified in the realms section, perhaps because the LDAP database back end is being used, or the file name is specified in the dbmodules section, then the hard-coded default for database_name is used. Determination of the iprop_logfile default value will not use values from the dbmodules section.)

Both primary and replica sides must have a principal named kiprop/hostname (where hostname is the lowercase, fully-qualified, canonical name for the host) registered in the Kerberos database, and have keys for that principal stored in the default keytab file (DEFKTNAME). The kiprop/hostname principal may have been created automatically for the primary KDC, but it must always be created for replica KDCs.

On the primary KDC side, the kiprop/hostname principal must be listed in the kadmind ACL file kadm5.acl, and given the p privilege (see Privileges).

On the replica KDC side, kpropd should be run. When incremental propagation is enabled, it will connect to the kadmind on the primary KDC and start requesting updates.

The normal kprop mechanism is disabled by the incremental propagation support. However, if the replica has been unable to fetch changes from the primary KDC for too long (network problems, perhaps), the log on the primary may wrap around and overwrite some of the updates that the replica has not yet retrieved. In this case, the replica will instruct the primary KDC to dump the current database out to a file and invoke a one-time kprop propagation, with special options to also convey the point in the update log at which the replica should resume fetching incremental updates. Thus, all the keytab and ACL setup previously described for kprop propagation is still needed.

If an environment has a large number of replicas, it may be desirable to arrange them in a hierarchy instead of having the primary serve updates to every replica. To do this, run kadmind -proponly on each intermediate replica, and kpropd -A upstreamhostname on downstream replicas to direct each one to the appropriate upstream replica.

There are several known restrictions in the current implementation:

• The incremental update protocol does not transport changes to policy objects. Any policy changes on the primary will result in full resyncs to all replicas.

• The replica’s KDB module must support locking; it cannot be using the LDAP KDB module.

• The primary and replica must be able to initiate TCP connections in both directions, without an intervening NAT.

Sun/MIT incremental propagation differences

Sun donated the original code for supporting incremental database propagation to MIT. Some changes have been made in the MIT source tree that will be visible to administrators. (These notes are based on Sun’s patches. Changes to Sun’s implementation since then may not be reflected here.)

The Sun config file support looks for sunw_dbprop_enable, sunw_dbprop_master_ulogsize, and sunw_dbprop_slave_poll.

The incremental propagation service is implemented as an ONC RPC service. In the Sun implementation, the service is registered with rpcbind (also known as portmapper) and the client looks up the port number to contact. In the MIT implementation, where interaction with some modern versions of rpcbind doesn’t always work well, the port number must be specified in the config file on both the primary and replica sides.

The Sun implementation hard-codes pathnames in /var/krb5 for the update log and the per-replica kprop dump files. In the MIT implementation, the pathname for the update log is specified in the config file, and the per-replica dump files are stored in LOCALSTATEDIR/krb5kdc/replica_datatrans_hostname.