O'Reilly logo

Kerberos: The Definitive Guide by Jason Garman

Stay ahead with the world's most comprehensive technology and business learning platform.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, tutorials, and more.

Start Free Trial

No credit card required

KDC Installation

With the boring planning out of the way, we’re ready to get down to the nitty-gritty of installing a KDC. We’ll cover each implementation in turn, and I’ll take you through building the software, all the way to setting up test users and distributing the Kerberos database among a network of slave KDCs.

This section covers the topics required to set up the KDC software. It does not cover related topics, such as security of the underlying operating system; these security-related topics can be found in Chapter 6.


Since the MIT Kerberos distribution is available as open source, there are two ways to install it: building it from source, or obtaining a binary distribution from your Unix vendor. As for Linux, many of the popular Linux distributions have pre-built binary packages of MIT Kerberos 5.

We’ll cover building MIT Kerberos from source for several reasons. One, many people feel more comfortable building security-sensitive applications directly from source. Also, some Unix distributions do not offer a pre-built MIT Kerberos distribution. Finally, by building from scratch, we can establish a common path structure and feature set that’s independent of any tweaks individual vendors have decided to include in their pre-built versions. If you prefer to install from pre-built packages, such as RedHat RPMS, feel free to skip over this section and continue on to the next section, Section

The MIT distribution is available for users in the U.S. and Canada at the MIT Kerberos home page, located at http://web.mit.edu/network/kerberos-form.html. Users in other countries should visit the Cryptography Publishing Project’s MIT Kerberos download page at http://www.crypto-publish.org/mit-kerberos5/index.html. The MIT Kerberos 5 source distribution is available at both sites, and the source code tarball available at both are bit-by-bit identical.

The source code distribution is signed with the PGP key of Tom Yu, a member of the MIT Kerberos development team. It is recommended that you verify the distribution you’ve downloaded against this signature, to ensure that the file has not been tampered with. If you obtained the source distribution from MIT, the signature is located within the tar file. If you obtained the source distribution from the Cryptography Publishing Project, the signature is located on the download web page. To verify the signature using the GNU Privacy Guard (a freely available implementation of PGP), ensure that the signature and the .tar.gz source tarball are in the same directory, and type:

% gpg --verify krb5-1.3.tar.gz.asc

where 1.3 is replaced with the latest version of the Kerberos distribution. Next, you’ll unpack the source distribution tarball:

% gzcat krb5-1.3.tar.gz | tar xfv -

This creates a krb5-1.3 directory, under which all of the files in the Kerberos source distribution are placed. Inside of the krb5-1.3 directory, there is a src and a doc directory. Since we want to build the distribution, switch to the krb5-1.3/src directory.

Building the distribution

The Kerberos 5 distribution builds much like many other Unix software packages, using the GNU autoconf configure process. Table 4-1 contains some configure options that you may want to change during the configure process. A list of all the options are available by using the standard --help option to the configure script.

Table 4-1. Configure options




Sets the directory prefix where the Kerberos binaries, libraries, documentation, and KDC databases are located. By default, everything will be installed under /usr/local ; however, some sites may want to change this to something else that fits their naming scheme.


Sets the directory prefix where the KDC databases will be located. Some sites may want to place the databases on a separate disk for performance and reliability reasons. By default, the KDC database is located underneath <prefix>/var


By default, the MIT Kerberos 5 distribution builds a small Kerberos 4 compatibility layer, so that the KDC can respond to Kerberos 4 requests and also to build a Kerberos 5-to-4 ticket conversion client library. This option disables the Kerberos 4 compatibility.




These options (and the corresponding —disable-dns.. options) determine whether the client libraries can use DNS to automatically determine Kerberos configuration. In particular, dns-for-realm switches the ability for clients to use DNS to find the realm name that they are a member of, and dns-for-kdc switches the ability for clients to use DNS to find the KDC for a given realm. The —enable-dns or —disable-dns options either enables or disables both of these options, respectively. By default, MIT Kerberos will use DNS for KDC lookups if information is not present in the Kerberos configuration file, /etc/krb5.conf. More information can be found in Section 4.5, later in this chapter


Enables the building of shared client libraries. By default, the client libraries are static. Note that shared libraries have not been thoroughly tested on most operating systems.

The defaults are sufficient in almost all cases, so we’ll go ahead and execute the configure script, then compile the distribution:

% ./configure && make


If you have trouble building the Kerberos distribution and get an error message such as cd: can't cd to obj, try using GNU Make instead of your vendor’s Make utility.

Once the make completes, install the software:

# make install

The install step establishes the directory structure under your prefix (/usr/local by default) and places the binaries, include files, and libraries in their appropriate places under the prefix directory.

Note, however, that the install process does not create the localstatedir (/usr/local/var by default). You’ll need to create this directory, as well as a krb5kdc directory underneath it, by yourself. In addition, you’ll want to set permissions on the krb5kdc directory to ensure that unauthorized users cannot access sensitive KDC data. An example for the default directory structure would be:

# mkdir /usr/local/var
# mkdir /usr/local/var/krb5kdc
# chown root /usr/local/var/krb5kdc
# chmod 700 /usr/local/var/krb5kdc

Creating your realm

Now we’ll use our new Kerberos installation to create our Kerberos realm. This step will only be performed on your master KDC. It creates the necessary database files and populates the KDC database with the necessary principals. First, we need to create some configuration files.

Strictly, the only configuration file that you need to create is a skeletal krb5.conf . The krb5.conf file lives in /etc, and contains parameters that are used by the Kerberos libraries. The krb5.conf file looks similar to a Windows-style ini file, with stanzas (or groups) in brackets, and key-value pairs separated by an equals sign. At this point, all you’ll need in this file is:

        default_realm = WEDGIE.ORG

        WEDGIE.ORG = {
                kdc = freebsd.wedgie.org:88
                admin_server = freebsd.wedgie.org:749
                default_domain = wedgie.org

        wedgie.org = WEDGIE.ORG
        .wedgie.org = WEDGIE.ORG

        kdc = FILE:/var/log/krb5kdc.log
        admin_server = FILE:/var/log/kadmin.log
        default = FILE:/var/log/krb5lib.log

Of course, replace all instances of WEDGIE.ORG and wedgie.org with your realm name and DNS domain name, respectively. Also, replace freebsd.wedgie.org with the fully qualified DNS name of the KDC you’re setting up. The log files specified in the logging stanza can go anywhere; however, we highly recommend that you include the logging section, as the logs will be useful for debugging as you implement Kerberos.


Kerberos is very picky when it comes to system hostnames and host lookups. Make sure that the hostname you place in the krb5.conf file actually resolves to the local machine. If you are just testing, an IP can be put in the krb5.conf file instead, in order to avoid any issues with host lookups.

Another configuration file that we’ll create is the KDC configuration file, kdc.conf .


The MIT Kerberos 5 distribution contains a program that can be used to test whether your hostnames and DNS resolver settings are set correctly. In the src/tests/resolve directory, the resolve program will output the system hostname, followed by the results obtained by a gethostbyname, followed by a gethostbyaddr on the returned IP address.

If you haven’t tweaked the prefix or localstatedir options in your configure process, then this file is located in /usr/local/var/krb5kdc. In general, this file (along with all of the KDC databases) lives under the krb5kdc directory of localstatedir, which defaults to <prefix>/var. Let’s look at a skeleton kdc.conf file:

        kdc_ports = 88,750

        WEDGIE.ORG = {
                database_name = /usr/local/var/krb5kdc/principal
                admin_keytab = /usr/local/var/krb5kdc/kadm5.keytab
                acl_file = /usr/local/var/krb5kdc/kadm5.acl
                dict_file = /usr/local/var/krb5kdc/kadm5.dict
                key_stash_file = /usr/local/var/krb5kdc/.k5.WEDGIE.ORG
                kadmind_port = 749
                max_life = 10h 0m 0s
                max_renewable_life = 7d 0h 0m 0s
                master_key_type = des3-hmac-sha1
                supported_enctypes = des3-hmac-sha1:normal des-cbc-crc:normal

More information on the parameters accepted by the Kerberos KDC in the kdc.conf file can be found in the manpage for kdc.conf. With the configuration files out of the way, we’re ready to actually initialize the Kerberos database. To perform this step, we’ll be using the kdb5_util program, included with the Kerberos distribution. This program performs various administrative tasks on the Kerberos database, which we’ll investigate later. For now, we’re going to use the create parameter to create a skeleton database for our new realm.

The following command line creates a new realm:

# /usr/local/sbin/kdb5_util create -s

Of course, adjust the path as necessary. The -s option indicates that we’ll be using a stash file to store what Kerberos calls the master key .

The master key is an encryption key that is used to encrypt the entire Kerberos database on disk. When the Kerberos KDC daemon starts, it first queries the console for the master key password; once the password is given, it can load the database in memory, decrypt it, and continue. Unfortunately, this password prompt prevents the KDC from starting automatically, since it requires human intervention to enter the password. Therefore, the password can be saved to disk in the form of a stash file. The -s option specifies that we want to create a stash file so that the KDC daemon can start without manual intervention.


It is important to note that the master key as described above is not the same as the Ticket Granting Ticket principal’s key (the key belonging to krbtgt/REALM@REALM). The master key is only used to encrypt the database on disk.

Let’s take a look at the dialog that is presented during a kdb5_util create command:

# /usr/local/sbin/kdb5_util create -s
Initializing database '/usr/local/var/krb5kdc/principal' for realm 'WEDGIE.ORG', 
master key name 'K/M@WEDGIE.ORG'
You will be prompted for the database Master Password.
It is important that you NOT FORGET this password.
Enter KDC database master key:
Re-enter KDC database master key to verify:

If you see an error such as:

Configuration file does not specify default realm while retreiving configuration 

This means you haven’t created a valid /etc/krb5.conf file with at least a default_realm defined.

Now the realm has been initialized, and some of the essential principals have already been created. Let’s take a quick look at what kdb5_util created for us. First, here are the files that we now have in our Kerberos database directory:

# ls -a /usr/local/var/krb5kdc
.                       principal               principal.ok
..                      principal.kadm5
.k5.WEDGIE.ORG          principal.kadm5.lock

The principal and principal.ok files are our Kerberos database files. The principal.kadm5 and principal.kadm5.lock files are the Kerberos administrative database and administrative database lock files, respectively. Finally, the .k5.WEDGIE.ORG file is our stash file, created by adding the -s option to kdb5_util.

Let’s see what principals were created for us. The program we’ll use is kadmin.local. Kadmin is the administrative interface to the Kerberos database; inside of kadmin, a Kerberos administrator can add principals, modify principals, delete principals, change passwords, and other administrative tasks. Normally, kadmin is run over a network from another machine, and requires you to authenticate (using Kerberos, of course) to a principal that has administrative privileges. Kadmin.local is a fail-safe copy of kadmin; it must be run locally on the KDC as root and modifies the KDC databases directly. Since we haven’t yet added any principals, let alone administrative principals, we have to use kadmin.local to access our newly formed database.

Let’s start kadmin.local:

# /usr/local/sbin/kadmin.local
Authenticating as principal jgarman/admin@WEDGIE.ORG with password.

Once in kadmin.local, we can list the principals we currently have in our KDC:

kadmin.local: listprincs

(Don’t worry, we’ll cover all of the commands available in kadmin in the Appendix.)

Now we’ll create an administrative principal. The traditional naming scheme for principals with administrative privileges is the username of the administrator with an instance of admin. Therefore, if your normal username is jdoe, your admin principal would be jdoe/admin. The following kadmin command will add a principal named jdoe/admin to your KDC:

kadmin.local:  addprinc jdoe/admin
WARNING: no policy specified for jdoe/admin@WEDGIE.ORG; defaulting to no policy
Enter password for principal "jdoe/admin@WEDGIE.ORG":
Re-enter password for principal "jdoe/admin@WEDGIE.ORG":
Principal "jdoe/admin@WEDGIE.ORG" created.

There is no need to worry about the policy warning; the policy that it is referring to is a password-aging and strength-checking policy. Since one hasn’t been created yet (we’ll see how to do that in Chapter 6), it warns us that none will be applied to our new principal.

Now when you perform a listprincs again, you’ll see your new administrative principal in the list. At this point, let’s go ahead and start our KDC. The KDC daemon process is named krb5kdc, and is located in <prefix>/sbin. Let’s go ahead and start it:

# /usr/local/sbin/krb5kdc

Here, no news is good news. If we get a prompt back with no error messages, the daemon should now be running in the background, responding to Kerberos client requests. Let’s go ahead and test it by logging in as our administrative user:

# /usr/local/bin/kinit jdoe/admin
Password for jdoe/admin@WEDGIE.ORG:

Once again, no news is good news.

Now, we’re going to add our new administrative user to the administrative access control list. Right now, jdoe/admin@WEDGIE.ORG has no administrative rights on the Kerberos server; we’ll have to define what rights that user has in the ACL file.

By default, the ACL file is named kadm5.acl and located in the same directory that your KDC databases are kept. The location and filename can be overridden by the acl_file parameter in kdc.conf. The file should contain a list of principals with administrative privilege, one per line, with several fields per line, separated by whitespace. The fields are:

  • Principal name

  • Permissions

  • Target principals for which the permissions apply (optional)

So, each line represents a permission granted or denied to a particular principal. The permission is defined by the principal name (the administrator the permissions apply to), the permissions being granted, and what principals those permissions can operate on (called the target principal ). Each line can override the line above; that is, permissions granted to a principal can be taken away by a later line.

In the principal name and the target principal parameters, a glob character of * can be used to match all of a given portion of a principal. For example, */admin@WEDGIE.ORG matches all usernames with an admin principal in the WEDGIE.ORG realm. * by itself matches all principals in all realms.

The permissions parameter is composed of single-letter permission options. A lowercase letter means that the user is granted the particular right the letter represents. An upper case letter means that the user is denied that right. Here are the possible permissions options:


Addition of users or policies into the KDC database


Deletion of users or policies from the KDC database


Modification of users or policies in the KDC database


Changing principals’ passwords in the KDC database


Inquiries into the database, to list principal information


Listing of the principals contained in the database

* (or x)

Grants the user all of the above permissions

So, for example, a permissions string of “acil” permits the user to add new users, change passwords of existing users, get detailed information about a principal, and list all principals in the database. All of the other permissions are denied.

The negative (uppercase) equivalents to these permissions do not become useful until you begin to combine them with the optional target principal parameter. This way, you can permit administrators to perform some administrative tasks on all users, then add negative permissions to deny them the permissions to administer other users.

Let’s take a look at an example. Our fictitious Wedgie organization has several administrators. We have two individuals in particular, Tyler Durden and Robert Paulson. Tyler is the senior system administrator at Wedgie, and Robert is a junior system administrator who is responsible for the maintenance of the normal user accounts. Therefore, we want to set up permissions so that Tyler has full access to modify any user principals, including administrative user principals and service principals. Since Robert is only responsible for normal user principals, we want to restrict his access so that he cannot modify administrative principals. Let’s see how we would accomplish this with the MIT ACL file:

tdurden/admin@WEDGIE.ORG     * 
rpaulson/admin@WEDGIE.ORG    * 
rpaulson/admin@WEDGIE.ORG    ADMICL     */admin@WEDGIE.ORG

To continue with our exercise, let’s give jdoe/admin permissions to administer all principals:

jdoe/admin@WEDGIE.ORG        *


The kadmind process will have to be restarted before changes in the kadm5.acl file will take effect.

Before we can use kadmin over the network, we need to create a keytab file containing the kadmin principals that were created when we initialized our realm. We’ll have to return to kadmin.local to perform this step, so restart it if you’ve exited out of it already. From the kadmin> prompt:

kadmin.local: ktadd -k /usr/local/var/krb5kdc/kadm5.keytab kadmin/admin kadmin/
Entry for principal kadmin/admin with kvno 3, encryption type Triple DES cbc mode 
with HMAC/sha1 added to keytab WRFILE:/usr/local/var/krb5kdc/kadm5.keytab.
Entry for principal kadmin/admin with kvno 3, encryption type DES cbc mode with CRC-
32 added to keytab WRFILE:/usr/local/var/krb5kdc/kadm5.keytab.
Entry for principal kadmin/changepw with kvno 3, encryption type Triple DES cbc mode 
with HMAC/sha1 added to keytab WRFILE:/usr/local/var/krb5kdc/kadm5.keytab.
Entry for principal kadmin/changepw with kvno 3, encryption type DES cbc mode with 
CRC-32 added to keytab WRFILE:/usr/local/var/krb5kdc/kadm5.keytab.

Of course, if you have changed the localstatedir to put the Kerberos database files in a different directory, adjust the /usr/local/var/krb5kdc path to the path where your database files reside.

Starting the servers

Now we’re ready to start the KDC server processes. There are several daemons that are included with the MIT Kerberos 5 package, and we’ll detail them in Table 4-2. Unless otherwise specified, these daemons run on the master KDC only. All of these servers can be found in /usr/local/sbin (for the default installation prefix of /usr/local).

Table 4-2. MIT Kerberos 5 daemons




The Kerberos 5 KDC itself. It runs on both the master and all of the slave KDCs.


A daemon to translate Kerberos 5 service tickets into Kerberos 4 tickets. Used for backwards-compatibility with Kerberos 4-based services. For more information on running krb524d, see Chapter 8.


The Kerberos 5 administration daemon. This daemon is the server component to the kadmin administrative client. It also handles password change requests.


The Kerberos 4 administration daemon. This daemon is only necessary for compatibility with the Kerberos 4 version of kadmin. Not required for Kerberos 4 compatibility unless you’re using the Kerberos 4 administrative tools for some reason. Not recommended for new installs.


Implements an old version of the Kerberos 5 password-changing protocol. This daemon is not needed on most installations, and there are only a few clients which speak this older password-changing protocol.


This is the Kerberos 5 database propagation daemon. Unlike the daemons above, this daemon is run only on the slave KDCs.

Typically, you’ll only need to run the krb5kdc and kadmind processes on your master KDC. If you need compatibility with older Kerberos 4 based services, such as the AFS filesystem, then you also may need to run the krb524d daemon, covered in Chapter 8. Let’s start the Kerberos daemon now (we started krb5kdc earlier):

# /usr/local/sbin/kadmind

Your MIT Kerberos 5 KDC is now ready to answer client authentication requests.

A quick test

Now let’s login with the administrative user that we created earlier, and use it to add a few other principals using the kadmin program. The commands that we’ll be using to perform this quick test can be run on any machine that has MIT Kerberos installed.

First, we’ll obtain tickets manually for our jdoe/admin@WEDGIE.ORG principal:

$ kinit jdoe/admin
Password for jdoe/admin@WEDGIE.ORG:


There are a few errors that can occur here. If you see Cannot contact any KDC for requested realm, ensure that the KDC daemon krb5kdc is running, and the realm that is printed when you run kinit matches the name of the realm that you just set up. Another possible error is Preauthentication failed, which simply means that you typed in your password incorrectly. More information about troubleshooting Kerberos error messages can be found in Chapter 5.

Now let’s go ahead and log into the kadmin administration server:

$ kadmin
Authenticating as principal jdoe/admin@WEDGIE.ORG with password.
Enter password:


If you see the error Cannot set GSS-API authentication names, you probably have not created the admin keytab correctly, or it is located in the wrong place.

Now let’s test your permissions; if you created the kadm5.acl file earlier, you should have full permissions for all principals in the database. Let’s go ahead and create a normal day-to-day user:

kadmin: addprinc jdoe
WARNING: no policy specified for jdoe@WEDGIE.ORG; defaulting to no policy
Enter password for principal "jdoe@WEDGIE.ORG":
Re-enter password for principal "jdoe@WEDGIE.ORG":
Principal "jdoe@WEDGIE.ORG" created.

Note that even if you don’t have permissions to create users, the kadmin program will continue to ask for a password for the new principal before giving an error message of:

add_principal: Operation requires ``add'' privilege while creating "jdoe@WEDGIE.ORG".

If you see this error message, make sure that the administrative user you’re logged in as has the permissions to create principals, as defined in the kadm5.acl file. The kadmind daemon needs to be restarted before changes in the ACL file become active.

Adding slave KDCs

If you’re setting up a network with only one KDC, you can stop here. We’re going to continue, and create some slave KDCs that will replicate the master Kerberos database and respond to client requests.

With MIT Kerberos, slave KDCs can answer client requests by issuing tickets, but cannot perform any operations that would modify the Kerberos database (such as changing passwords). In other words, slave KDCs have a read-only copy of the Kerberos database. All updates must go through the master KDC. Updates are periodically distributed to the slave KDCs in a push model. A cron job running on the master KDC periodically sends a complete copy of the Kerberos database to the slave KDCs over an encrypted and authenticated connection.

The first step is to build the MIT Kerberos distribution on each of the slave KDCs. The same procedure detailed above in Section should be repeated on each of your slave KDCs.

Once MIT Kerberos is installed, we can continue by extracting host keytabs for each of the slave KDCs. The Kerberos database propagation mechanism uses these keytabs to securely transfer the database between the master and slave KDCs. Log into each KDC, connect to kadmin, create a host principal for the machine, and extract the new key into the hosts’ keytab:

slave# /usr/local/sbin/kadmin
Authenticating as principal jgarman/admin with password.
Enter password:
kadmin: addprinc -randkey host/slave.wedgie.org
WARNING: no policy specified for host/slave.wedgie.org@WEDGIE.ORG; defaulting to no 
Principal "host/slave.wedgie.org@WEDGIE.ORG" created.
kadmin: ktadd host/slave.wedgie.org
Entry for principal host/slave.wedgie.org with kvno 3, encryption type Triple DES cbc 
mode with HMAC/sha1 added to keytab WRFILE:/etc/krb5.keytab.
Entry for principal host/slave.wedgie.org with kvno 3, encryption type DES cbc mode 
with CRC-32 added to keytab WRFILE:/etc/krb5.keytab.

Enter these kadmin commands on each slave, using the slave’s hostname as the name of the host principal. Follow the same procedure on the master KDC to create a host principal for the master KDC.

Once all of the principals have been created and appended to the keytabs of the KDC machines, add the names of these principals to the database propagation ACL file on each KDC. Log into each KDC and create a file in the Kerberos database directory (by default, /usr/local/var/krb5kdc) named kpropd.acl . This file must contain the host principals of all KDCs participating in your realm, with one principal listed per line. An ACL file for our test network would look like the following:


If this file does not exist, or does not contain the host principals for all participating KDCs, you will get an error message in the system log when attempting to distribute the Kerberos database to slave KDCs.

The kpropd.acl file lists all of the principals that are authorized to connect to the KDCs Kerberos database propagation service. In a typical setup, only the master KDC distributes the Kerberos database to slave machines; so you only need to list the master KDC’s host principal in each slave KDC’s kpropd.acl file. However, it is a good strategy to put all KDCs in this file, so that it is easier to make another KDC temporarily the master in case the master KDC fails and is unavailable for a long period.

Next, create an entry in each KDC’s /etc/inetd.conf file so that they listen for connections to the Kerberos database propagation server. Insert a line such as the following, changing the program path as necessary on each KDC:

krb5_prop  stream   tcp  nowait  root  /usr/local/sbin/kpropd  kpropd

Ensure that you have an entry for krb5_prop in your /etc/services file. If an entry does not exist, add the following line to your /etc/services file:

krb5_prop  754/tcp

After modifying the inetd.conf file, restart inetd so the changes take effect.

Now that we have an ACL file, we can go ahead and dump the database, and send a copy to our slave KDC. The following commands, executed on the master KDC, will create a copy of the Kerberos database and then send that copy to the slave KDC:

master# /usr/local/sbin/kdb5_util dump /usr/local/var/krb5kdc/slavedump
master# /usr/local/sbin/kprop -f /usr/local/var/krb5kdc/slavedump slave.wedgie.org
Database propagation to slave.wedgie.org: SUCCEEDED

If, instead of the above success message, you receive an error message, check to make sure that the machine’s hostname and DNS name match, the keytabs have been created on each KDC with the appropriate host principals, and the ACL file on your slave KDCs list the host principals of the other KDCs.

We’ll have to create a stash file to hold the Kerberos master key on each of our slave KDCs. Remember that the Kerberos database is encrypted on disk by a master key. When the database is dumped and transferred over the network to the slave KDCs, the database is still protected by the master key and cannot be read without it. So now we’ll initialize the slave KDCs’ stash files by entering our master key. The master key entered here must match the master key given when initializing the realm on the master KDC.

slave# /usr/local/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:

If you get an error after entering your master key, then it does not match the master key that the realm was created with.

Now for one last step. While we’ve succeeded in transferring our master KDC’s database over the network to a slave, we’ll need to automate the process if we expect it to happen on a regular basis. To that end, we need to create a cron job that will dump the Kerberos database and distribute it to our slave KDCs. Here is an example shell script that performs this task:


# Distribute KDC database to slave servers
# Created by Jason Garman for use with MIT Kerberos 5

# Configurables
slavekdcs="slave.wedgie.org slave-2.wedgie.org"


${krb5prefix}/sbin/kdb5_util dump ${slavedata}
if [ $error -ne 0 ]
        echo "Kerberos database dump failed with exit code $error.  Exiting."
        exit 1

for kdc in $slavekdcs
        ${krb5prefix}/sbin/kprop -f ${slavedata} ${kdc}
        if [ $error -ne 0 ]
             echo "Propagation of database to host ${kdc} failed with exit code $error."
             echo "Continuing with other slave servers."

if [ $success -eq 1 ]
        echo "Kerberos database successfully replicated to all slaves."

Finally, place this shell script in the crontab of your master KDCs so that it executes on a regular basis. A typical interval between database replications is an hour.

At this point, your Kerberos realm has at least one KDC, and possibly several additional slave KDCs, ready to serve Kerberos clients. A Kerberos realm is not complete without clients and application servers; we’ll cover adding them to your Kerberos realm later in Section 4.6, later in this chapter.


Just like MIT, Heimdal is also an open source implementation of Kerberos 5. Many Unix distributions have pre-built Heimdal packages, but like MIT, we will cover building Heimdal from source.

Since Heimdal is under development and is distributed from Sweden, it is unencumbered by United States export restrictions and is freely available for download worldwide. Heimdal is a complete clean-room implementation of the Kerberos 5 protocol specification, and as such contains no MIT Kerberos 5 code.

The current version of the Heimdal Kerberos 5 package as of this writing is 0.6. Don’t let the small version number dissuade you from using Heimdal; while it hasn’t been in development quite as long as MIT Kerberos 5, it is feature-complete for the basic Kerberos 5 protocol, and includes as standard features some features that MIT Kerberos doesn’t have, such as incremental database propagation.

Heimdal depends on another package, kth-krb, to enable Kerberos 4 backwards-compatibility. We won’t cover building kth-krb; it has a build process similar to Heimdal, and the only configuration option that you may want to tweak is the prefix directory for the installed binaries and libraries (/usr/athena by default). The source distribution of kth-krb is available from http://www.pdc.kth.se/kth-krb/.

The Heimdal home page is http://www.pdc.kth.se/heimdal/, where you’ll be able to download the latest version of the Heimdal source code.

Building the distribution

After unpacking the tar file, you’ll have a heimdal-0.6 directory (or whatever the latest version is). Heimdal uses the GNU autoconf configure process. Table 4-3 lists some of the more important options that the Heimdal configure script recognizes.

Table 4-3. Heimdal options




Sets the directory prefix where the Kerberos binaries, libraries, documentation, and KDC databases are located. By default, everything will be installed under /usr/local; however, some sites may want to change this to something else that fits their naming scheme.


Gives the configure program the prefix directory where the Kerberos 4 include files and libraries are located. If you installed the kth-krb distribution, this option can be used to tell the Heimdal configure program where you’ve installed the kth-krb Kerberos 4 libraries.


Heimdal can either link against OpenSSL or an internal DES library for cryptography support. By default, Heimdal will look for OpenSSL in some standard locations, such as /usr and /usr/local. If you have OpenSSL installed in another directory, set this configuration option to the root directory of your OpenSSL installation.


By default, Heimdal will compile support for IPv6 in the KDC and user libraries (if your operating system supports IPv6 sockets). Use this option to disable the IPv6 support in Heimdal.


By default, Heimdal keeps its Kerberos database in a local file on the KDC’s file system. It can keep the database in LDAP, however. We won’t cover putting the KDC database in LDAP, but this option allows you to specify the root directory of your OpenLDAP installation. For more information about using an LDAP backend to Heimdal, see http://www.padl.com/Research/Heimdal.html.

Typically, the default parameters are sufficient. Remember that if you need your KDC to service Kerberos 4 clients, or have services that require Kerberos 4 tickets, you’ll need to specify the --with-krb4 option, indicating the directory where you have kth-krb installed. We’ll go ahead and configure with the default options, and make the distribution:

% ./configure && make

If all went well, install the distribution:

# make install

The installation process doesn’t create the directory where the KDC databases are kept, namely /var/heimdal. This directory is hardcoded in the Heimdal distribution so the easiest solution to place the database in another directory is to symlink /var/heimdal to the desired location. We’ll create the /var/heimdal directory now, and set the permissions so that unauthorized users cannot access the contents of this sensitive directory:

# mkdir /var/heimdal
# chown root /var/heimdal
# chmod 700 /var/heimdal

Creating your realm

In this step, we will create the skeleton database files that will define the principals in our new realm. These steps are only performed on the master KDC server.

Just like with MIT Kerberos, we must create a few configuration files before we continue. Also, these configuration files are similar to the ones we use with MIT. They are broken into stanzas, or categories, contained in brackets, with key/value pairs separated by an equal sign. Our first file is /etc/krb5.conf . Here is a sample /etc/krb5.conf:

        default_realm = WEDGIE.ORG

        WEDGIE.ORG = {
                kdc =
                admin_server =

        .wedgie.org = WEDGIE.ORG

We’ll come back to examine the krb5.conf file format in more detail in the Appendix. For now, you’ll want to ensure that your default_realm parameter is set to the realm name you’re about to set up. Define your KDC address in the realms stanza, and that domain_realm contains a mapping from your KDC’s domain name (with a leading dot prepended) to your new realm name.

If your KDCs’ domain name is equal to the realm name (ignoring case), then you can omit the libdefaults and domain_realm stanzas, since the Kerberos libraries will be smart enough to figure those out on their own.

Heimdal can encrypt the KDC database on disk with a master key. Heimdal will save the password to a stash file also located in /var/heimdal. This feature is mostly used to protect backups of the KDC database from being easily readable by attackers, assuming that the database is backed up separate from the stash file. If you wish to create a master key and a stash file, use the kstash command:

# /usr/heimdal/sbin/kstash
Master key:
Verifying password - Master key:
/usr/heimdal/sbin/kstash: writing key to `/var/heimdal/m-key'

Now we will initialize our realm. We will use the kadmin program, which can be used from any Heimdal client to administer principals on the KDC. Since our KDC isn’t running yet, we’ll have to run it in the local mode, to access the database directly on disk. This is accomplished by giving the -l option to kadmin:

# /usr/heimdal/sbin/kadmin -l

You should get back a prompt of kadmin>. This is the kadmin interface. We’ll use the init command to create our new realm:

kadmin> init WEDGIE.ORG
Realm max ticket life [unlimited]:1d
Realm max renewable ticket life [unlimited]:1w

At this point, kadmin asks us some questions about the ticket policies in the new realm. Good defaults for the maximum ticket life and renewable ticket life are typically one day and one week, respectively. Shorthand date formats such as the ones above will work, including h for hour and m for minute. We’ll cover kadmin in detail in the Appendix.

Now you have a realm with a skeleton set of principals. Let’s see what principals are there:

kadmin> list *

We’ll cover the kadmin command set in more detail later in Appendix A; for now, I’ll say that the list command lists principals that match a glob pattern—in this case *, meaning every principal. The default principals that are created out of the box include default, which is a pseudoprincipal (tickets cannot be issued for it) whose attributes are used as the defaults for any new principals that are created. Also, we have a few kadmin principals; these principals are internal KDC service principals that handle the administrative interface protocol, database replication, and the Kerberos password change service. Finally, we have the krbtgt principal, which is the Ticket Granting Ticket principal for our realm.

Inside our Kerberos database directory, we now have a few files. First, we have m-key , which is the master key password for the Kerberos database. Then, Heimdal creates the KDC log file by default as kdc.log inside of this directory. Last but not least, we have the Kerberos database file itself, heimdal.db .

Next, we’ll add an admin user. By convention, this should be your usual username with an instance of admin. You can name it whatever you like; however, I recommend that it be separate from the principal that you use for everyday use, and of course with a different password. To create our principal, we first must be in kadmin (if you’ve exited it already, simply run it again with the -l option).

At the kadmin> prompt:

kadmin> add jdoe/admin
Max ticket life [1 day]:
Max renewable life [1 week]:
Principal expiration time [never]:
Password expiration time [never]:
Attributes []:
jdoe/admin@WEDGIE.ORG's Password:
Verifying password - jdoe/admin@WEDGIE.ORG's Password:

For now, we’ll take the defaults.

Next, we have to create an Access Control List so that this new administrative user can actually log in via kadmin. Heimdal stores the ACL file in the Kerberos database directory (the default location is /var/heimdal/kadmind.acl). Each line of this file contains the following three fields, separated by whitespace:

  • Administrative principal

  • Permissions

  • Target principal (optional)

Each line of the ACL file defines a permission or list of permissions granted to the principal (first field) to perform on the target principal. Both the principal and target principal fields can contain shell glob characters to specify a set of principals. The permissions field can be a comma-separated list of any of the following permissions:


The user can add principals into the Kerberos database.

change-password (or cpw)

The user can change the password of an existing principal in the Kerberos database.


The user can delete principals in the Kerberos database.

get (or list)

The user can retrieve detailed information on a given principal or set of principals from the Kerberos database.


The user can modify principal’s attributes in the Kerberos database.


A combination of all the above rights.

An example ACL line would be:

jdoe/admin@WEDGIE.ORG all

This ACL entry will give the user jdoe/admin@WEDGIE.ORG administrative rights to perform any operation on all principals in the realm. Note that adding an ACL entry with an empty target principal field applies the permissions to all principals on the KDC. If a * were placed in the target principal field, it would only match principals with no instance component (for example, * would match jdoe, but not jdoe/admin).

If a permission is not specified in the permissions field, it is not granted by default. Since the permission field itself is optional, by not granting any permissions to an administrative principal, you deny it all permissions. Note that there is currently no way to specify negative permissions, so an approach to give an administrator control over all users who do not have admin instances could not be expressed as giving the administrator all privileges over all principals, then giving the administrator no privileges over admin instance principals. Instead, you can give the administrator all privileges over all principals with no instance (by using a single * in the target principal field). While this differs slightly from what we originally set out to do (what about principals with instances other than admin, such as service and host principals?), it is probably what was intended in the first place, and permissions to act on other instances can be added to the ACL file if needed.

Since all of these rules can be confusing, let’s take an example:

jgarman/admin@WEDGIE.ORG   all     *
jgarman/admin@WEDGIE.ORG   get     */otherinstance
jdoe/admin@WEDGIE.ORG      all     */admin

This set of permissions allows the jgarman/admin principal to perform all operations on principals with no instance component, and only perform get (or list) operations on principals with an instance component of “otherinstance.” All other operations on other principals are denied. Similarly, jdoe/admin is allowed to perform all administrative operations only on principals with an admin instance, but no others. All other principals have no administrative rights.


Note that Heimdal is very sensitive to whitespace in the kadmind.acl file—a stray space or tab at the end of the target principal will be treated as part of the target principal. Since principals cannot contain spaces, the line in the ACL file will not match any principal and will not work as intended.

To continue with the exercise, place the following in your kadmind.acl file:

jdoe/admin@WEDGIE.ORG all

This statement will allow the jdoe/admin@WEDGIE.ORG principal to perform all administrative operations on every principal in the realm.

Starting the servers

Now that our Kerberos database has been successfully initialized, we’re ready to start the Kerberos daemons on the master KDC. There are several daemons that are included with Heimdal (shown in Table 4-4), each of which serves a different purpose. If you did not change the prefix when building the software, you can find these servers in /usr/heimdal/libexec. Unless otherwise specified, these daemons should be run only on the master KDC.

Table 4-4. Master KDC daemons




This is the KDC server process. The Heimdal kdc server includes support for Kerberos 5, Kerberos 4, and the Kerberos 5-to-4 ticket translator (the latter two are only enabled if Kerberos 4 support was compiled in to the distribution at build time). This process should be run on all KDCs on your network.


This is the administrative daemon for the Heimdal KDC. This process must be run on the master KDC (and only the master KDC) if you want to administer the Kerberos database over the network.


This server handles Kerberos password-change requests. Heimdal separates out password-changing from the kadmind server, and uses this process to handle client password-change requests. This daemon should be run only on your master KDC, since it changes the Kerberos database directly.


This server receives the Kerberos database from the master KDC and writes it to a slave KDC’s disk. Therefore, this daemon should only be run on slave KDCs. It can work in tandem with the iprop-server and iprop-client to support incremental propagation, which we’ll cover in a bit when we add slave KDCs to our network.

Let’s start the common services we’ll need (kdc, kadmind, and kpasswdd):

# /usr/heimdal/libexec/kdc &
# /usr/heimdal/libexec/kpasswdd &
# /usr/heimdal/libexec/kadmind &

A quick test

Now that our realm is established, let’s test our installation to make sure everything is functioning. Login with the jdoe/admin principal:

% kinit jdoe/admin
jdoe/admin@WEDGIE.ORG's Password:

As long as no errors are output, everything went well. Let’s go ahead and login to the kadmin server:

% kadmin
kadmin> list -l jdoe/admin
jdoe/admin@WEDGIE.ORG's Password:
               Principal: jdoe/admin@WEDGIE.ORG
       Principal expires: never
        Password expires: never
    Last password change: never
         Max ticket life: 1 day
      Max renewable life: 1 week
                    Kvno: 6
                   Mkvno: 0
                  Policy: none
   Last successful login: never
       Last failed login: never
      Failed login count: 0
           Last modified: 2002-11-10 15:53:34 UTC
                Modifier: jgarman/admin@WEDGIE.ORG
Keytypes(salttype[(salt-value)]): des3-cbc-sha1(pw-salt), des-cbc-md5(pw-salt), des-
cbc-md4(pw-salt), des-cbc-crc(pw-salt)

Adding slave KDCs

If you’re setting up a network with only one KDC, you can stop here. Otherwise, we’re going to create some slave KDCs that will replicate the master Kerberos database and respond to client requests.

With Heimdal Kerberos, slave KDCs can answer client requests by issuing tickets, but cannot perform any operations that would modify the Kerberos database (such as changing passwords). In other words, slave KDCs have a read-only copy of the Kerberos database. All updates must go through the master KDC. Updates are periodically distributed to the slave KDCs in a push model. A cron job running on the master KDC periodically sends a complete copy of the Kerberos database to the slave KDCs over an encrypted and authenticated connection.

The first step is to build the Heimdal Kerberos distribution on each of the slave KDCs. The same procedure detailed above in Section should be repeated on each of your slave KDCs.

First, we’ll have to add a host principal for each slave server. We will log into each slave server in turn, create a new principal, and extract it into a keytab. The ktutil program included with Heimdal can create a principal with a random key and extract it into a keytab with one operation, so we’ll use it to create our host principal.

slave# /usr/heimdal/sbin/ktutil get host/slave.wedgie.org

Now, we’ll add the Heimdal propagation server to the slave’s inetd.conf file. A line such as the following should be sufficient:

krb5_prop  stream tcp  nowait root /usr/local/libexec/hpropd hpropd

Note that krb5_prop must be a valid entry in /etc/services that maps to the Heimdal Kerberos propagation port, namely 754. Once inetd has been restarted so that the hpropd is listening on the slave, we can force the master to distribute a full copy of the Kerberos database to our new slave:

master# /usr/heimdal/sbin/hprop slave

Obviously, you’ll want to automate this process so that it happens on a regular basis. You can enter the hprop command above in your crontab to occur regularly. Most Kerberos sites set this up to replicate hourly; however, your site may have different requirements. Multiple slave Kerberos servers can be updated at the same time by listing their hostnames on the hprop command line.

Heimdal also supports incremental database propagation, where instead of transferring the entire database at preset intervals, updates are sent to slaves as changes are made to the master database. This option is much more efficient with network resources and also makes updates appear to slaves (and consequently to end users) almost immediately. As this feature is still undergoing development, we won’t cover the details here, but the Heimdal documentation available at http://www.pdc.kth.se/heimdal/heimdal.html describes the procedure required to enable incremental database propagation.

Windows Domain Controller

The Windows 2000 and 2003 Domain Controller is the Windows equivalent of a Unix-based KDC. You’ll need Windows 2000 Server or Windows 2003 Server to create a domain controller.

Therefore, to establish a Windows-based KDC, you must establish an Active Directory domain. Microsoft has a wizard that steps you through this process. While this book doesn’t cover the intricacies of Active Directory, we will explore the basic steps required to create a domain controller on a Windows 2000 or 2003 Server machine.

Once again, this quick guide to setting up a Kerberos realm using a Windows server machine is not intended to be a full introduction to Active Directory. Instead, this section will guide you through the necessary steps to establish a working Kerberos realm using your Windows server as a KDC, where both Windows machines and Unix boxes can participate as clients.

Creating your realm

First, log into the machine that will become the new domain controller with an account that has local Administrator privileges. Start by executing the dcpromo command from the command line. This command starts the Active Directory Wizard. If the machine isn’t already a domain controller, you’ll see the window shown in Figure 4-1.

Active Directory Wizard welcome screen

Figure 4-1. Active Directory Wizard welcome screen

When you click Next, it will continue to the next step of the wizard, shown in Figure 4-2.

Active Directory Controller Type dialog

Figure 4-2. Active Directory Controller Type dialog

You’ll want to create a new domain. Continue with the defaults until you get to the domain name dialog, shown in Figure 4-3.

Selecting the domain name for the new Active Directory domain

Figure 4-3. Selecting the domain name for the new Active Directory domain

The answer to this dialog box will become the name for the new Active Directory domain, and should be the same as your organization’s DNS name. Note that the resulting Kerberos realm created by the wizard will be this name, converted to uppercase. So if your domain name is example.com, the Kerberos realm that the Active Directory wizard creates for you will be named EXAMPLE.COM.

The NetBIOS name that you choose in the next dialog does not affect your Kerberos realm in any way; the default should be sufficient. The next step presents you with the option of where to place the Kerberos database files and log files (Figure 4-4).

Active Directory Database Location dialog

Figure 4-4. Active Directory Database Location dialog

As we discussed earlier, it is good practice to store these files on separate disks, separate from each other and the disk holding the operating system.

The next dialog asks where the SYSVOL files should be kept. Once again, this option has no bearing on the functioning of the Kerberos KDC and the default is sufficient. Once you’ve clicked Next on that dialog box though, you may encounter the message depicted in Figure 4-5.

Active Directory warning message when no DNS server supporting dynamic updates is authoritative for the new domain

Figure 4-5. Active Directory warning message when no DNS server supporting dynamic updates is authoritative for the new domain

This message appears if there is no Windows or other DNS server supporting or dynamic updates that are authoritative for the DNS domain associated with your realm. In this case, you’ll probably want to set up DNS on your new domain controller, and you’ll see the configure DNS dialog pictured in Figure 4-6.

Creating a DNS server for your new Active Directory domain

Figure 4-6. Creating a DNS server for your new Active Directory domain

The next two steps in the AD wizard ask for information that is irrelevant to the proper operation of Kerberos. For our purposes, the defaults work fine.

After you click the Finish button on the wizard, the configuration process is automatically started. This process may take several minutes, depending on the speed of your machine. Once the process finishes, the wizard will ask you to reboot the computer. Once the machine reboots, it is now a Domain Controller and a Kerberos KDC. Other Windows 2000/XP/2003 machines that join the new Windows domain will now use Kerberos to authenticate domain user logins. Interoperability between Windows domain controllers and Unix Kerberos clients and application servers will be covered in depth in Chapter 8.


Note that this process does not affect the primary or secondary DNS server settings of the local system. If the system is set up to use a DNS server that does not delegate the new DNS domain created during this process to the new Active Directory server, then the dynamic DNS updates and other Active Directory processes will fail. See Q244669 on the Microsoft Support site for more details.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, interactive tutorials, and more.

Start Free Trial

No credit card required