A.2 Configuration File Format

Both MIT and Heimdal use the same basic format for their text configuration file, krb5.conf. This file contains all of the information needed for the Kerberos libraries that are linked into Kerberos clients, servers, administrative utilities, and the KDC itself. Since this file is rather standardized between the major Kerberos implementations on Unix, a krb5.conf file generated for one can easily be used on another implementation, usually with no changes required.

While normally this configuration file is located in /etc, an alternate location can be defined by setting the KRB5_CONFIG environment variable. Both MIT and Heimdal honor this environment variable. For example, in a Bourne shell, the following command would instruct further Kerberos applications to use the /etc/krb5.conf.backup file as the Kerberos configuration file instead:

% export KRB5_CONFIG=/etc/krb5.conf.backup

The krb5.conf file is comprised of a number of key-value pairs, organized into groups, referred to as stanzas. Stanza names are enclosed in opening and closing brackets, and each key/value pair must belong to one stanza. Key/value pairs are separated by an equals sign, with the key name on the left and its associated value on the right of the equals sign. The value in a key/value pair can either be a single value, or it can be another set of key/value pairs, enclosed by braces. The most common example of this is in the realms stanza, where a key is defined for each realm, whose value is another set of key/value pairs defining the KDC and other important servers in that realm. That is, each key/value pair can take on of the two following forms:

key = value

keyWithSubkeys = {
    subkey1 = value
    subkey2 = value
};

A sample krb5.conf file is shown below:

[libdefaults]
        default_realm = SAMPLE.COM

[realms]
        SAMPLE.COM = {
                kdc = kerberos.sample.com:88
                kdc = kerberos-2.sample.com:88
                admin_server = kerberos.sample.com
        };

        W2K.SAMPLE.COM = {
                kdc = windows.sample.com:88
        };

[domain_realm]
        .sample.com = SAMPLE.COM
        sample.com = SAMPLE.COM
        testbox.sample.com = W2K.SAMPLE.COM
        windows.sample.com = W2K.SAMPLE.COM

This krb5.conf file defines three stanzas: libdefaults, realms, and domain_realm. These are the most common stanzas that are present in krb5.conf files and they represent the basic data that every Kerberos client and service needs to have in order to participate in the Kerberos protocol. The following six stanzas can be present in this file: libdefaults, appdefaults, realms, domain_realm, capaths, and logging. Additional stanzas may be defined by other implementations. We'll cover each of these stanzas in turn.

A.2.1 libdefaults

This stanza contains parameters relevant to the operation of the Kerberos library. The settings in this stanza apply globally to all of the Kerberos library functions for applications running on this host. Available settings in this stanza include:

default_realm

This is the most important setting in the krb5.conf file. The default_realm key defines the default realm that Kerberos clients and services will use. This should be set to the realm that this machine is a member of.

clockskew

The clockskew key defines the amount of time in seconds that the Kerberos library will allow two clocks to differ by and still consider the message valid. By default this setting is 300 seconds, or 5 minutes.

default_tkt_enctypes

This key defines the list of session key encryption types that the KDC will return to clients. This list can be separated by whitespace or commas. For example:

default_tkt_enctypes = des3-hmac-sha1 des-cbc-crc

default_tgs_enctypes

This key defines the list of session key encryption types requested by the Kerberos client libraries. This parameter takes the same type of options as the default_tkt_enctypes key above.

noaddresses

Setting this key to "yes" will cause the Kerberos library to request addressless tickets from the KDC. This option can be helpful when using NAT. More information on the affect of NAT on Kerberos can be found in Section 6.5.2 in Chapter 6.

A.2.2 appdefaults

The appdefaults stanza contains configuration parameters for individual Kerberized client and server applications. The Kerberos library includes functions to read parameters from this stanza, so some Kerberized applications may place Kerberos-specific configuration information into the krb5.conf file in the appdefaults stanza.

A.2.3 realms

The realms stanza contains parameters that are configurable on a per-realm basis. The most important configuration information contained in this stanza is the list of authoritative KDCs for each realm that this client will communicate with. Also, if settings in the global appdefaults stanza (described above) must be overridden for some Kerberos realms, key/value pairs that are valid for appdefaults may be placed in an appropriate realm entry in the realms stanza.

Each realm entry is comprised of a key whose name is a Kerberos realm. The value is a set of key/value pairs, which define the properties of that realm. The following settings can be found inside of a realm section:

kdc

Each kdc key defines one KDC in the realm. Multiple kdc directives can be listed when multiple KDCs are present in a realm. An optional port number can follow the domain name of the kdc in this directive, but as all Kerberos 5 implementations listen on the standardized Kerberos port, 88, this port number is not required.

admin_server

The admin_server key defines the Kerberos administrative server for this realm. This would typically be the master KDC for the realm, and is the server that clients will contact for services such as the kadmin service or password changing requests.

Note that the KDC configuration information may also be stored in DNS SRV records, as covered in Chapter 4.

A.2.4 domain_realm

This stanza defines the DNS domain name to Kerberos realm mappings used by the Kerberos libraries when performing service name canonicalization. When an application wishes to connect to a Kerberized server, it has to acquire a service ticket from the KDC. However, the client requires some method to determine what Kerberos realm, and consequently, what service principal, that it needs to request, and also what KDC to contact. Currently, the MIT and Heimdal distributions use the DNS domain name of the server, coupled with the domain_realm mapping, to determine what Kerberos realm that the server belongs to.

By default, if there is no domain_realm entry for a given hostname, a machine is assumed to be in the realm formed by the domain portion of the hostname, converted to all uppercase. For example, the server bigserver.sample.com would be assumed to be in the realm SAMPLE.COM. Note that this policy would place the server sample.com inside of a realm named COM, which probably isn't what you want.

The domain_realm stanza contains a list of key/value pairs, where the key is a DNS hostname or domain name, and the value is the associated Kerberos realm for that key. Domain-to-realm mappings for an entire DNS subdomain begin with a single dot (.) to signify that the realm mapping applies to any hosts inside of the given subdomain. Note that more specific entries override less specific ones. For example, given the domain_realm stanza given at the beginning of this section:

[domain_realm]
        .sample.com = SAMPLE.COM
        sample.com = SAMPLE.COM
        testbox.sample.com = W2K.SAMPLE.COM
        windows.sample.com = W2K.SAMPLE.COM

Two of the machines, testbox.sample.com and windows.sample.com, belong to the W2K.SAMPLE.COM Kerberos realm. All of the other hosts inside of the sample.com domain, including the host sample.com itself, are located in the SAMPLE.COM realm.

A.2.5 logging

This stanza defines the auditing parameters of both the Kerberos library and KDC. The contents of this stanza are covered in detail in Chapter 6.

A.2.6 capaths

The capaths stanza defines the certification paths that are used during cross-realm authentication to find the path authentication requests should take from one realm to another. Cross-realm authentication and the use of the capaths stanza are covered in Chapter 8.