Setting Up a Kerberos Server

The core of a Kerberized network is the Kerberos server ”the KDC. As with most Linux servers, it's configured through a plain-text configuration file stored in /etc . Understanding this file's format allows you to control the Kerberos server, and thus to exercise some control over other systems on the network. This chapter cannot present details of every aspect of Kerberos operation, but this section does describe the basics of configuring the server. Subsequent sections discuss configuring Kerberos clients and application servers.

NOTE

Some of the configuration steps described in this section must also be performed on Kerberos clients and Kerberos application servers. For instance, you must set up realms in the same way on all systems (described shortly in "Setting Up a Realm").

The Kerberos package must be installed on the KDC, of course. If you obtain the MIT source code, you can compile and install it in the usual way, by using a script called configure included in the package, followed by the commands make and make install . This will install the Kerberos server, Kerberos application servers, and Kerberos clients. I recommend you use the --enable-shared option to configure ; this compiles Kerberos libraries in a shared form, which reduces the size of individual Kerberos programs. Some third-party Kerberos packages rely on such a configuration. Binary packages may break Kerberos components up into separate package files. For instance, Red Hat's Kerberos distribution includes packages called krb5-libs , krb5-server , and krb5-workstation . You can fine-tune your installation by omitting unnecessary packages.

Modifying Server Configuration Files

The main Kerberos server configuration file is /etc/krb5.conf . This file consists of sections, each of which is headed by a keyword in square brackets ( [] ). Subsequent lines, up until the next heading, define features related to that heading. Listing 6.1 shows a sample krb5.conf file for a KDC.

Listing 6.1 Sample krb5.conf File

 [logging]  default = FILE:/var/log/krb5libs.log  kdc = FILE:/var/log/krb5kdc.log  admin_server = FILE:/var/log/kadmind.log [libdefaults]  ticket_lifetime = 24000  default_realm = THREEROOMCO.COM  dns_lookup_realm = false  dns_lookup_kdc = false [realms]  THREEROOMCO.COM = {   kdc = kerberos.threeroomco.com:88   kdc = kerberos-1.threeroomco.com:88   kdc = kerberos-2.threeroomco.com:88   admin_server = kerberos.threeroomco.com:749   default_domain = threeroomco.com  } [domain_realm]  .threeroomco.com = THREEROOMCO.COM  threeroomco.com = THREEROOMCO.COM  outsider.threeroomco.com = PANGAEA.EDU [kdc]    profile = /var/kerberos/krb5kdc/kdc.conf 

Within each section, each line consists of a variable name , an equal sign ( = ), and the value assigned to the variable. Some sections include subsections, indicated by curly braces ( {} ). For instance, the [realms] section of Listing 6.1 uses curly braces to identify the lines associated with the THREEROOMCO.COM realm. This allows you to create a file that supports multiple realms.

NOTE

Kerberos application servers and clients need most of the same sections in krb.conf as does the KDC, but you can omit the [logging] and [kdc] sections from these systems. Some specific programs may require their own settings. These frequently go in a section called [appdefaults] .

The KDC also uses its own configuration file, kdc.conf , which is often stored in /var/kerberos/kdc5krb , /usr/local/var/kdc5krb or a similar location, specified in the [kdc] section of krb5.conf . This file contains information specific to the KDC, as opposed to the krb5.conf file, which is used by the KDC, Kerberos clients, and Kerberos application servers. The format of the kdc.conf file is similar to that of krb5.conf .

Setting Up a Realm

The usual way to configure a realm entails making certain realm-specific entries in the krb5.conf and kdc.conf files. In the case of the former file, you make these changes on the KDC, the application servers, and the clients. You then restart the Kerberos server and application server programs to initiate the changes.

Changing krb5.conf

The krb5.conf file contains a [realms] section that specifies the KDC and its slaves. There's also a [domain_realm] section that defines the relationship between the realm and an Internet domain. Listing 6.1 shows examples of both sections.

The [realms] section in this example specifies the master KDC and two slave KDCs for the THREEROOMCO.COM realm. These servers are conventionally called kerberos and kerberos- n , where n is a number signifying the slave number, within the domain corresponding to the realm. Although in this example the domain and realm have the same name (aside from case), this need not always be true, as noted earlier. Each of the KDC specifications includes the port number on which the KDC listens for connections ”normally 88. The admin_server entry specifies a computer that's used to administer the realm. This is often the same as the KDC, but the administrative functions use a different port ”normally 749. The default_domain entry specifies the domain name associated with Kerberos principals. The default is the Kerberos realm name converted to lowercase, so in this example this entry isn't strictly necessary.

It's possible to specify multiple realms with a single krb5.conf file. To do so, you include a single [realms] section, but list multiple realm names , each of which contains its specifics within its own set of curly braces ( {} ).

TIP

When configuring a DNS server to handle your domain, you may want to use a CNAME entry to specify the KDC hostnames as listed in the krb5.conf file and elsewhere. This way, you can quickly and easily change the computer that functions as the KDC in the event of network problems or restructuring, without modifying numerous Kerberos configuration files scattered throughout the realm. Another option is to use virtual IP addresses ”one system using Network Address Translation (NAT; see Chapter 25) is listed in the DNS server as the KDC, but it forwards its requests to another computer, which actually runs the KDC software. Thus, you can easily move KDC functions from one computer to another without adjusting your DNS entries.

The [domain_realm] section maps computers into specific Kerberos realms based on their hostnames or domain names. The format lists a hostname or domain name (the latter indicated by a leading period, as in .threeroomco.com ) followed by an equal sign and the Kerberos realm to which the machine or machines belong. Listing 6.1 maps all computers in the threeroomco.com domain (including any computer known only as threeroomco.com ) to the THREEROOMCO.COM realm, with one exception: outsider.threeroomco.com belongs to the PANGAEA.EDU domain.

Changing kdc.conf

The kdc.conf file contains entries that are similar to those in krb5.conf . Listing 6.2 shows an example kdc.conf file. You'll have to make realm- specific changes in the [realms] section. Most importantly, you need to change the name of the realm ( EXAMPLE.COM in many default configuration files). The [realms] section also contains entries that set the types of encryption keys the realm supports, but you shouldn't change these unless you fully understand the consequences. The [kdcdefaults] section points the server to various important configuration files.

Listing 6.2 Sample kdc.conf File

 [kdcdefaults]   acl_file = /var/kerberos/krb5kdc/kadm5.acl   dict_file = /usr/share/dict/words   admin_keytab = /var/kerberos/krb5kdc/kadm5.keytab [realms]   THREEROOMCO.COM = {     master_key_type = des-cbc-crc     supported_enctypes = des-cbc-crc:normal des3-cbc-raw:normal \ des3-cbc-sha1:normal des-cbc-crc:v4 des-cbc-crc:afs3   } 

Creating a Master Key

Kerberos relies on a master key to control access to itself. This key is essentially a password, and it may be stored locally in a stash file, which is a file that the server reads sto allow itself to start up automatically. Without the stash file, the server requires manual intervention at startup ”somebody must type in the master key.

Because of its critical nature, the stash file should be stored only on a disk that's local to the KDC, and be readable only by root . You shouldn't back up this file unless the backup is very closely guarded . You should apply the usual rules for selection of a master key that you use for any password ”it shouldn't be a dictionary word, name, or be derived from personal data that an attacker might gain from public sources. You should use a mixed-case string of letters , numbers , and punctuation that's as close to random as you can make it and still remember it. A good starting point is an acronym based on some phrase you can remember, such as yiwttd for yesterday I went to the dentist. Randomly change the case of some letters and add punctuation and numbers. The result might be yi9Wt%Td.

To create a master key and store it in a stash file, use the kdb5_util command:

 #  kdb5_util create -r THREEROOMCO.COM -s  Initializing database '/var/kerberos/krb5kdc/principal' for realm 'THREEROOMCO.COM', master key name 'K/[e-mail]' 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: 

NOTE

As a security precaution, the master key doesn't echo to the screen, but you must type it at the prompts to enter it.

This command creates or initializes several files in the /var/kerberos/ krb5kdc directory, or some other location a given Kerberos package uses for this purpose, such as /usr/local/var/krb5kdc . These files include:

• The stash file, which may be called .k5. REALM.NAME , where REALM.NAME is the realm name; or .k5stash .

• Two Kerberos database files, principal and principal.ok . (The principal file is called principal.db on some systems.)

• Two Kerberos administrative files, principal.kadm5 and principal. kadm5.lock .

If you don't want to use a stash file, you can omit the -s from the kdb5_util command; this will cause the program to not create the stash file. You'll then need to enter the Kerberos master key whenever you start the server.

Administering a Realm

Once you've modified the Kerberos configuration files for your realm and used kdb5_util to create a master key and initialize the Kerberos databases, you can begin administering the realm. This process is essentially one of defining principals, including some that have administrative privileges to add other principals.

Defining Basic ACLs

Kerberos principal information is stored in the form of Access Control Lists (ACLs), which are stored in the file pointed to by the acl_file entry in kdc.conf . This file consists of lines with the following format:

  Kerberos principal     Permissions     Target principal  

NOTE

Kerberos ACLs aren't quite the same as ACLs in filesystems like XFS, although they're both access control mechanisms. Filesystem ACLs allow you to specify who may access a file in particular ways. Kerberos ACLs specify who may modify the Kerberos database in particular ways. Kerberos ACLs do not rely upon ACL support in the filesystem.

Table 6.1. Permission Codes for the ACL File

Code	Meaning
a	Allows the addition of principals or policies
A	Forbids the addition of principals or policies
d	Allows the deletion of principals or policies
D	Forbids the deletion of principals or policies
m	Allows the modification of principals or policies
M	Forbids the modification of principals or policies
c	Allows changing passwords for principals
C	Forbids changing passwords for principals
i	Allows inquiries into the database
I	Forbids inquiries into the database
l	Allows the listing of principals or policies in the database
L	Forbids the listing of principals or policies in the database
x or *	Wildcard for all "allows" ACLs ( admcil )

The first entry ( Kerberos principal ) is a principal name, as described earlier. You can use an asterisk ( * ) as a wildcard in part of the principal name to match anything. For instance, you might use */[e-mail] to match any primary with an instance of admin in the THREEROOMCO.COM domain. Such a definition is useful to grant administrators uniform access to the KDC.

The second entry ( Permissions ) is a code for the ACLs granted to the principal. Each type of permission is signified by a single-letter code, as shown in Table 6.1. You can merge multiple codes to grant multiple types of access, as in ali to allow a principal to add users, list principals, or make inquiries of the database.

The final entry ( Target principal ) is optional, and provides the names of principals to which the preceding permissions apply. For instance, you might want to limit a given user 's ability to access or modify rights for particular principals. As with the Kerberos principal , the Target principal may use an asterisk as a wildcard.

As an example, consider the following entry:

 */[e-mail]   * 

This entry gives all principals in the admin instance full access to the Kerberos database. An entry similar to this is the default. As a starting point, you may want to modify it to point to your realm and otherwise leave it alone.

Creating Principals

You use the kadmin or kadmin.local programs to administer your Kerberos user database. The former program uses encrypted Kerberos communications to administer a KDC from a remote system; the latter modifies the local database files directly, without using network tools. You must use kadmin.local to add at least one administrative user. Thereafter, you can theoretically use kadmin from other systems in much the same way, although of course you must have appropriate Kerberos administrative servers running on the KDC, which at this point in the process they are not.

Both programs accept various parameters to modify the principal name with which you attempt to modify the database, the realm you attempt to administer, and so on. The kadmin man page provides details on these. Once you've started the program, you enter commands at its prompt. For instance, to add the principal admin/[e-mail] , you would use the addprinc command, as follows :

 #  kadmin.local  Authenticating as principal root/[e-mail] with password. kadmin.local:  addprinc admin/[e-mail]  WARNING: no policy specified for admin/[e-mail]; defaulting to no policy Enter password for principal "admin/[e-mail]": Re-enter password for principal "admin/[e-mail]": Principal "admin/[e-mail]" created. 

NOTE

As usual when entering passwords, they don't echo to the screen, but you must type them. You should not reuse the Kerberos master key as an administrative password, or for that matter use either of these as any other password.

After you've created an administrative principal, you must create a keytab for the administrative principal. This is a key that Kerberos uses to decrypt administrative tickets. You don't need to specify this key yourself; Kerberos can generate it. You do need to tell Kerberos to do so, though, using the ktadd command within kadmin.local :

 kadmin.local:  ktadd -k /var/kerberos/krb5kdc/kadm5.keytab \   kadmin/admin kadmin/changepw  

You specify the file in which the keytab is stored by preceding the filename with -k . This file should match the one specified in the kdc.conf file's admin_keytab entry. You then list the principals for which you want to add keytabs ” kadmin/admin and kadmin/changepw in this case. (These two principals are a standard part of Kerberos; you don't need to explicitly create them.)

In addition to these administrative principals, you should add principals for your users, application servers, and KDCs. You do this with the addprinc command, which works much as described earlier. For instance, suppose you want to add a principal for [e-mail] . You might enter:

 kadmin.local:  addprinc [e-mail]  

For servers, you may want to use the -randkey option, which tells the system to use a randomized key for this principal. If you don't use this option, you'll be prompted to enter a password. There are many other options you can use as well; the kadmin man page explains them.

Application server entries are added in the same way, but they're typically called service / hostname @ REALM.NAME , where service is the service name (such as pop or ftp ), hostname is the hostname, and REALM.NAME is the realm name. You also need one entry in which service is host . In addition, you must extract the host's keytab with the ktadd command, as described earlier. Extract each keytab into a unique file (that is, use a different parameter to -k for each host). You'll subsequently move this file to the application server itself. Alternatively, you can later use kadmin from the computer that hosts the application server to create a principal for the server, and use ktadd to extract the keytab directly on the application server computer.

You may want to add a principal for each KDC. These principals are generally of the form host/ host.name @ REALM.NAME , such as host/kerberos-1. threeroomco.com/THREEROOMCO.COM . Although these aren't strictly required in slave KDCs, they can be helpful if ordinary users will be logging into the KDC (which is generally not recommended) or if you need to swap in a slave KDC in place of a master KDC. The master KDC requires this principal in order to propagate its database to slave KDCs.

When you're done with kadmin , you can exit from the program by typing quit at its main prompt.

Starting the KDC

At this point, Kerberos is configured enough to start it. You can do so through the methods described in Chapter 4, Starting Servers. If your Kerberos package was built for your distribution or a sufficiently similar one, it should come with one or more SysV startup scripts, such as krb5kdc for the KDC and kadmin for the administrative server.

If you don't have SysV startup scripts, you can start the KDC processes by running the krb5kdc and kadmin programs that came with the package. Each program should fork from the shell, so you don't need to follow their names with ampersands ( & ). You can run these programs from startup scripts such as /etc/rc.d/rc.local .

Configuring a Slave KDC

Slave KDCs are configured in much the same way as master KDCs. In particular, you should set up the krb5.conf and kdc.conf files just as you do for a master KDC, use kdb5_util to create database files, set up an ACL file, and use the ktadd command in kadmin.local to extract a keytab file.

Each KDC requires a file that lists all the KDCs (or more precisely, the principals associated with those KDCs) for database propagation purposes. This file is called kpropd.acl , and it's stored in /var/kerberos/krb5kdc , /usr/local/var/krb5kdc , or a similar location. This file might resemble the following:

 host/[e-mail] host/[e-mail] 

Once you've configured this file on all your KDCs, you must set up the slave KDCs to run a pair of servers, kpropd and klogind . You can do this by modifying your super server to run them. For instance, appropriate /etc/inetd.conf entries look like this:

 krb5_prop stream tcp nowait root /usr/kerberos/sbin/kpropd kpropd eklogin   stream tcp nowait root /usr/kerberos/sbin/klogind \ klogind -k -c -e 

You may need to change the location of the executable files, and of course if you use xinetd , you'll need to create an appropriate xinetd configuration instead. (Chapter 4 covers both super servers.) If your /etc/services file doesn't include entries for krb5_prop and eklogin , you must add them. These entries look like this:

 krb5_prop       754/tcp           # Kerberos slave propagation eklogin         2105/tcp          # Kerberos encrypted rlogin 

The propagation is handled on the master KDC. It involves two steps: dumping the database and sending it to slaves. A script that handles both tasks appears in Listing 6.3 ”but you'll have to make appropriate changes for your own network, as well as your own installation (such as the location of the dump file). If your network uses more than one slave, you'll need a separate kprop call for each slave, or you can write a script that uses a loop to propagate the dump to each slave. You can call this script from a cron job to have it run automatically at whatever interval is appropriate for your network.

Listing 6.3 Sample Script for Propagating a Kerberos Database to Slave KDCs

 #!/bin/sh /usr/kerberos/sbin/kdb5_util dump /usr/kerberos/var/krb5kdc/slave_datatrans /usr/kerberos/sbin/kprop -f /usr/kerberos/var/krb5kdc/slave_datatrans \    kerberos-1.mi1.threeroomco.com