Linux in a Windows World

Kerberos Realm Configuration

MIT Kerberos uses two configuration files: krb5.conf and kdc.conf. Heimdal, though, dispenses with the latter file, so you needn’t be concerned with kdc.conf if you’re configuring Heimdal. The krb5.conf file contains assorted information about your realm and the server’s operation, while the kdc.conf file contains KDC-specific information.

Tip

Application servers and clients need to know much of the realm information in krb5.conf, and so these systems use this file, as well, although some sections are missing or ignored on these systems.

Editing krb5.conf

The KDC’s main configuration file is called krb5.conf. If you install Kerberos from a package, chances are this file will reside in /etc. A sample krb5.conf file appears in Example 9-1.

Example 9-1. Sample krb5.conf listing

[logging]
 default = FILE:/var/log/krb5libs.log
 kdc = FILE:/var/log/krb5kdc.log
 admin_server = FILE:/var/log/kadmind.log

[libdefaults]
 ticket_lifetime = 28800
 default_realm = EXAMPLE.COM
 dns_lookup_realm = false
 dns_lookup_kdc = false

[realms]
 EXAMPLE.COM = {
  kdc = kdc.example.com:88
  admin_server = kdc.example.com:749
  default_domain = example.com
 }

[domain_realm]
 .example.com = EXAMPLE.COM
 tropical.pangaea.edu = EXAMPLE.COM

This file is broken into sections, with each section denoted by a section name within square brackets ([ ]). Most options span a single line and consist of an option name followed by an equal sign and its value. Some, though, use compound values, which themselves span multiple lines. These are denoted by curly braces ({ }), as in the EXAMPLE.COM item within the [realms] section. Many of the krb5.conf parameters are self-explanatory, but some deserve additional elaboration:

Logging options: The options in the [logging] section tell the server where to log data related to Kerberos operation. This section is not required for application server and client installations, just for KDCs.
Ticket lifetime: The ticket_lifetime option sets the default lifetime for most tickets issued by the KDC, in seconds. The value of 28800 shown in Example 9-1 corresponds to eight hours. A too-long lifetime increases the risk of security breaches caused by stolen tickets, while a too-short lifetime will be inconvenient for users because they have to reinitialize their Kerberos sessions.
Default realm: The default_realm option sets the realm that the KDC is to manage. This is likely to be named after your DNS domain name, but it doesn’t have to be.
DNS lookup options: The dns_lookup_realm and dns_lookup_kdc options tell Kerberos to use DNS to help locate systems.
Realm definitions: The [realms] section defines realms. In Example 9-1, one realm is defined: http://EXAMPLE.COM. This definition includes pointers to a single KDC and one administrative server. (If your realm has slave KDCs, they’re defined just like the master, using a kdc line.) The administrative server handles administrative functions, such as adding principals; it’s normally the same as the master KDC. These definitions include port numbers—88 for the KDC and 749 for the administrative server. The default_domain option specifies the DNS domain name that’s associated with Kerberos principals, when appropriate. A single krb5.conf file may define multiple realms. In such cases, you’d define each in its own set of lines, in a single [realms] section.
Domain/realm mapping: The [domain_realm] section specifies a mapping of computers to realms. In Example 9-1, all computers in the http://example.com domain and the computer http://tropical.pangaea.edu are included in the http://EXAMPLE.COM realm. Subdomains are indicated by a leading dot (.); entries lacking this dot are interpreted as referring to individual computers.

In addition to the entries shown in Example 9-1, MIT Kerberos is likely to have an additional section that points to the kdc.conf file:

[kdc]
  profile = /var/kerberos/krb5kdc/kdc.conf

You may also see a section called [appdefaults] in sample configuration files. This section modifies settings for individual application servers and clients. For instance, you might increase or decrease a ticket lifetime based on the likely session length for a particular service.

Editing kdc.conf

MIT Kerberos implementations typically place some KDC options in a separate file, called kdc.conf, which are referred to by a profile option in the [kdc] section of krb5.conf. Example 9-2 shows a typical example of this file. You should leave most of these options alone, but you can change the name of the Kerberos realm on the first line of the [realms] section to match your needs. The master_key_type and supported_enctypes options relate to the encryption methods that Kerberos supports.

Example 9-2. Sample kdc.conf listing

[kdcdefaults]
 acl_file = /var/kerberos/krb5kdc/kadm5.acl
 dict_file = /usr/share/dict/words
 admin_keytab = /var/kerberos/krb5kdc/kadm5.keytab
 v4_mode = nopreauth

[realms]
 EXAMPLE.COM = {
  master_key_type = des-cbc-crc
  supported_enctypes = arcfour-hmac:normal arcfour-hmac:norealm 
arcfour-hmac:onlyrealm 
des3-hmac-sha1:normal des-hmac-sha1:normal des-cbc-md5:normal 
des-cbc-crc:normal des-cbc-
crc:v4 des-cbc-crc:afs3
}

Creating a Master Key

Because of the high priority Kerberos places on security, it uses a cryptographic master key to control access to itself. Without this key, Kerberos won’t start. The key is generated from a password, and it’s possible to store this password in a stash file . Using a stash file, Kerberos can start automatically when the computer boots; without a stash file, you must enter a password whenever you start the server.

In Heimdal, the utility to create a master key and a stash file is called kstash . (Heimdal actually creates a single file for both purposes.) To perform this task, type this command:

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

As with most utilities that ask for passwords, kstash doesn’t echo the password you type. MIT Kerberos uses another utility, kdb5_util, to create its master key and stash file:

# kdb5_util create -r EXAMPLE.COM -s
Loading random data
Initializing database '/var/kerberos/krb5kdc/principal' for realm 'EXAMPLE.COM',
master key name 'K/M@EXAMPLE.COM'
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:

Warning

The master key, stash file, and password are all extremely sensitive. The utilities should create files with appropriate permissions to protect them (typically 0600), at least assuming the Kerberos server isn’t compromised. You should be extremely careful to both remember the password and not let it fall into unauthorized hands. Pick a password that’s as close to a random collection of letters, digits, and punctuation as possible without running the risk of forgetting it, and don’t re-use this password for any other account or server.

Realm Administration

At this point, your KDC is nearly ready to be used; however, you must still set up principals and define access control rules. Both tasks are critical for normal Kerberos operations. In fact, you’re likely to return to these tasks, and particularly principal creation, many times in the future.

Creating principals

Principals are, essentially, Kerberos accounts. Kerberos requires certain principals in order to function, and you’ll presumably want to create principals for your ordinary users. This section describes both tasks. Application servers also require principals, but this task is described in Section 9.3.2.

Kerberos provides a tool called kadmin to manage principals. Ordinarily, this tool connects to the Kerberos administrative server (specified by the admin_server option in krb5.conf) to manage principals. At this point, though, this server isn’t running because it’s not yet fully configured, so you must create principals without using this server. In Heimdal, this task is accomplished by passing the -l option to kadmin. In MIT Kerberos, you use a variant command, kadmin.local . In Heimdal, the interaction for initializing the realm looks like this:

# kadmin -l
kadmin> init EXAMPLE.COM
Realm max ticket life [unlimited]:
Realm max renewable ticket life [unlimited]:
kadmin> add admin/admin@EXAMPLE.COM
Max ticket life [1 day]:
Max renewable life [1 week]:
Principal expiration time [never]:
Password expiration time [never]:
Attributes [  ]:
admin/admin@EXAMPLE.COM's Password:
Verifying - admin/admin@EXAMPLE.COM's Password:

The init command initializes the Kerberos database; it should be the first command you type when you use this program for the first time. The add command adds a principal for the administrative user. (You can use other primary and instance names if you like, though the principal should be in your realm.) If you’re using MIT Kerberos, there’s no need to begin with the init command, and the add command is called addprinc . You do, however, need to use the ktadd command to prepare a keytab, which is a special key Kerberos uses to handle administrative principals:

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

The system should respond with a rather verbose report concerning the creation of the keytab files.

Whether you’re using Heimdal or MIT Kerberos, you might want to take the time now to create at least one or two test accounts. These accounts might not have instance names for simplicity’s sake. You can also omit the realm name, if you’re adding a principal to your default realm:

kadmin> add fluffy

Heimdal is more verbose in the questions it asks at this point, and you can select the default for most of these. Whichever server you’re using, though, you’ll have to enter a password.

Tip

Once you’ve started the KDC and the kadmind server, you can use kadmin to administer the server remotely, with one caveat: you can’t use the kadmin from MIT Kerberos to administer a Heimdal server or vice versa; the administrative protocols aren’t compatible.

ACL definitions

Kerberos uses ACLs to determine who may access the server (that is, kadmind, not the KDC as a whole) and in what ways. Kerberos ACLs are conceptually similar to filesystem ACLs, but they’re not identical, nor do they rely on filesystem ACLs. Kerberos ACLs are defined in a special ACL file. In Heimdal, this file is normally /var/heimdal/kadmind.acl; in MIT Kerberos, it’s the file pointed to by the acl_file entry in kdc.conf. (You can specify the same parameter in a [kdc] section in Heimdal’s krb5.conf file, if you want to use another file in Heimdal.) The ACL file consists of a series of lines, each with two or three entries:

                     Kerberos-Principal  Permissions  [Target-Principal]

The first entry, Kerberos-Principal, is the principal to which the ACL applies—that is, the user whose permissions are being defined. The Permissions string is a collection of one or more letters (in MIT Kerberos) or a comma-separated list of codes (in Heimdal), as summarized in Table 9-1, that define the operations the user can perform. If no third option is present, these permissions apply to all other principals. If a third entry is present, however, it refers to the principals that the first principal may modify in the specified ways. For instance, you might want to give some users the ability to modify certain classes of principals but not others.

Table 9-1. Kerberos ACL permission codes

MIT Kerberos code	Heimdal code	Meaning
`a`	`add`	Principals or policies can be added.
`A`	-	Principals or policies can’t be added.
`d`	`delete`	Principals or policies can be deleted.
`D`	-	Principals or policies can’t be deleted.
`m`	`modify`	Principals or policies can be modified.
`M`	-	Principals or policies can’t be modified.
`c`	`cpw` or `change-password`	Passwords can be changed.
`C`	-	Passwords can’t be changed.
`i`	`get`	Database inquiries can be made.
`I`	-	Database inquiries can’t be made.
`l`	`list`	Principals or policies can be listed.
`L`	-	Principals or policies can’t be listed.
`x` or `*`	`all`	Wildcard for all “can” ACLs (`admcil`).

In the case of both principal specifications, an asterisk (*) can be used as a wildcard for part of the specification. For instance, you can give all users in the admin instance the ability to do anything in MIT Kerberos:

*/admin@EXAMPLE.COM  *

In MIT Kerberos, an entry similar to this is the default, but you should modify it to point to your realm. You might also want to fine-tune the ACLs to suit your own needs—for instance, providing different groups of administrators different levels of access to the server’s administrative functions. In Heimdal, the ACL file is absent by default, so you’ll probably want to create it. A failure to create this file means that you can’t perform administrative tasks from other systems, including adding principals and extracting keytabs—tasks that are required for adding application servers to a Kerberos realm. (You can still perform these tasks from the KDC itself, but then you’ll have to move highly sensitive keytab files to the application server in some other way, such as on a floppy disk or via a network file transfer.)

Running the KDC

The KDC must be run in order to be useful. On most Linux distributions, you can do this by running a SysV startup script:

# /etc/init.d/kdc start

Details vary from one distribution to another, though; the script may be called kdc, krb5kdc, mit-krb5kdc, or something else. You may need to use your distribution’s package system or simply peruse your SysV startup scripts to locate the correct script.

Some KDC startup scripts start the Kerberos administrative server along with the KDC server. Others, though, provide a separate script to start the administrative server. This second script may be called mit-krb5kadmind, kadmin, or something else. Again, checking the SysV scripts installed with your package or perusing the startup scripts may be necessary. Normally, you’ll want to run the administrative server on the master KDC; without it, your ability to administer your realm from anything but the KDC itself will be limited.

Starting the KDC and administrative server manually is fine for testing, but, in operation, you’ll probably want to configure your system to start the servers on a regular basis. On many distributions, the chkconfig command can be used to do this:

# chkconfig --add kdc

Other distributions use other tools to do this job. Consult distribution-specific documentation if you need help with this task.

Table of Contents for
Linux in a Windows World

Linux Kerberos Server Configuration

Kerberos Realm Configuration

Tip

Editing krb5.conf

Editing kdc.conf

Creating a Master Key

Warning

Realm Administration

Creating principals

Tip

ACL definitions

Running the KDC

Table of Contents for Linux in a Windows World

Linux Kerberos Server Configuration

Kerberos Realm Configuration

Tip

Editing krb5.conf

Editing kdc.conf

Creating a Master Key

Warning

Realm Administration

Creating principals

Tip

ACL definitions

Running the KDC

Table of Contents for
Linux in a Windows World