Home > Guides > Security > General Security and Privacy

Security Reference Guide

Hosted by

Toggle Open Guide Table of ContentsGuide Contents

Close Table of ContentsGuide Contents

Close Table of Contents

Kerberos Implementation, Part 5

Last updated May 23, 2003.

Heimdal

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 3 lists some of the more important options that the Heimdal configure script recognizes.

Table 3. Heimdal options

Option

Description

--prefix=<dir>

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.

--with-krb4=<dir>

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.

--with-openssl=<dir>

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.

--without-ipv6

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.

--with-openldap=<dir>

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:

[libdefaults]
    default_realm = WEDGIE.ORG

[realms]
    WEDGIE.ORG = {
        kdc = 192.168.0.4
        admin_server = 192.168.0.4
    }

[domain_realm]
    .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 its 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.

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

kadmin> list *
 default@WEDGIE.ORG
 kadmin/admin@WEDGIE.ORG
 kadmin/hprop@WEDGIE.ORG
 kadmin/changepw@WEDGIE.ORG
 krbtgt/WEDGIE.ORG@WEDGIE.ORG
 changepw/kerberos@WEDGIE.ORG

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:

add 

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.

delete 

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.

modify 

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

all 

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

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), 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. Master KDC daemons

Daemon

Purpose

kdc

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.

kadmind

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.

kpasswdd

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.

hpropd

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
       Attributes:
Keytypes(salttype[(salt-value)]): des3-cbc-sha1(pw-salt), des-cbc-md5(pw-salt), des-
cbc-md4(pw-salt), des-cbc-crc(pw-salt)