15.7. Kerberos5
Prev | Chapter 15. Security | Next

## 15.7. Kerberos5

Contributed by Tillman Hodgson.
Based on a contribution by Mark Murray.

Kerberos is a network add-on system/protocol that allows users to authenticate themselves through the services of a secure server. Kerberos can be described as an identity-verifying proxy system. It can also be described as a trusted third-party authentication system. After a user authenticates with Kerberos, their communications can be encrypted to assure privacy and data integrity.

The only function of Kerberos is to provide the secure authentication of users on the network. It does not provide authorization functions (what users are allowed to do) or auditing functions (what those users did). It is recommended that Kerberos be used with other security methods which provide authorization and audit services.

This section provides a guide on how to set up Kerberos as distributed for FreeBSD. Refer to the relevant manual pages for more complete descriptions.

For purposes of demonstrating a Kerberos installation, the various name spaces will be as follows:

- The DNS domain (“zone”) will be `example.org`.

- The Kerberos realm will be `EXAMPLE.ORG`.

### Note:

Use real domain names when setting up Kerberos even if it will run internally. This avoids DNS problems and assures inter-operation with other Kerberos realms.

### 15.7.1. History

Kerberos was created by MIT as a solution to network security problems. The Kerberos protocol uses strong cryptography so that a client can prove its identity to a server (and vice versa) across an insecure network connection.

Kerberos is both the name of a network authentication protocol and an adjective to describe programs that implement it, such as Kerberos telnet. The current version of the protocol is version 5, described in RFC 1510.

Several free implementations of this protocol are available, covering a wide range of operating systems. The Massachusetts Institute of Technology (MIT), where Kerberos was originally developed, continues to develop their Kerberos package. It is commonly used in the US as a cryptography product, and has historically been affected by US export regulations. The MIT Kerberos is available as the `security/krb5` package or port. Heimdal Kerberos is another version 5 implementation, and was explicitly developed outside of the US to avoid export regulations. The Heimdal Kerberos distribution is available as a the `security/heimdal` package or port, and a minimal installation is included in the base FreeBSD install.

These instructions assume the use of the Heimdal distribution included in FreeBSD.

### 15.7.2. Setting up a Heimdal KDC

The Key Distribution Center (KDC) is the centralized authentication service that Kerberos provides. It is the computer that issues Kerberos tickets. The KDC is considered “trusted” by all other computers in the Kerberos realm, and thus has heightened security concerns.

While running the Kerberos server requires very few computing resources, a dedicated machine acting only as a KDC is recommended for security reasons.

To begin setting up a KDC, ensure that `/etc/rc.conf` contains the correct settings to act as a KDC. As required, adjust paths to reflect the system:

kerberos5_server_enable="YES" kadmind5_server_enable="YES"

Next, edit `/etc/krb5.conf` as follows:

[libdefaults] default_realm = EXAMPLE.ORG [realms] EXAMPLE.ORG = { kdc = kerberos.example.org admin_server = kerberos.example.org } [domain_realm] .example.org = EXAMPLE.ORG

This `/etc/krb5.conf` implies that the KDC will use the fully-qualified hostname `kerberos.example.org`. Add a CNAME (alias) entry to the zone file to accomplish this if the KDC has a different hostname.

### Note:

For large networks with a properly configured DNS server, the above example could be trimmed to:

[libdefaults] default_realm = EXAMPLE.ORG

With the following lines being appended to the `example.org` zone file:

_kerberos._udp IN SRV 01 00 88 kerberos.example.org. _kerberos._tcp IN SRV 01 00 88 kerberos.example.org. _kpasswd._udp IN SRV 01 00 464 kerberos.example.org. _kerberos-adm._tcp IN SRV 01 00 749 kerberos.example.org. _kerberos IN TXT EXAMPLE.ORG

### Note:

For clients to be able to find the Kerberos services, it must have either a fully configured `/etc/krb5.conf` or a minimally configured `/etc/krb5.conf` and a properly configured DNS server.

Next, create the Kerberos database which contains the keys of all principals encrypted with a master password. It is not required to remember this password as it will be stored in `/var/heimdal/m-key`. To create the master key, run kstash(8) and enter a password.

Once the master key has been created, initialize the database using `kadmin -l`. This option instructs kadmin(8) to modify the local database files directly rather than going through the kadmind(8) network service. This handles the chicken-and-egg problem of trying to connect to the database before it is created. At the kadmin(8) prompt, use `init` to create the realm's initial database.

Lastly, while still in kadmin(8), create the first principal using `add`. Stick to the default options for the principal for now, as these can be changed later with `modify`. Type `?` at the kadmin(8) prompt to see the available options.

A sample database creation session is shown below:

`#` `kstash` Master key: `xxxxxxxx` Verifying password - Master key: `xxxxxxxx` `#` `kadmin -l` kadmin> `init EXAMPLE.ORG` Realm max ticket life [unlimited]: kadmin> `add tillman` Max ticket life [unlimited]: Max renewable life [unlimited]: Attributes []: Password: `xxxxxxxx` Verifying password - Password: `xxxxxxxx`

Next, start the KDC services. Run `service kerberos start` and `service kadmind start` to bring up the services. While there will not be any kerberized daemons running at this point, it is possible to confirm that the KDC is functioning by obtaining and listing a ticket for the principal (user) that was just created from the command-line of the KDC itself:

`%` `kinit `tillman`` tillman@EXAMPLE.ORG's Password: `%` `klist` Credentials cache: FILE:`/tmp/krb5cc_500` Principal: tillman@EXAMPLE.ORG Issued Expires Principal Aug 27 15:37:58 Aug 28 01:37:58 krbtgt/EXAMPLE.ORG@EXAMPLE.ORG

The ticket can then be revoked when finished:

`%` `kdestroy`

### 15.7.3. Kerberos Enabling a Server with Heimdal Services

First, copy `/etc/krb5.conf` from the KDC to the client computer in a secure fashion, such as scp(1), or physically via a removable media.

Next, create `/etc/krb5.keytab`. This is the major difference between a server providing Kerberos enabled daemons and a workstation: the server must have a `keytab`. This file contains the server's host key, which allows it and the KDC to verify each others identity. It must be transmitted to the server in a secure fashion, as the security of the server can be broken if the key is made public.

Typically, the `keytab` is transferred to the server using kadmin(8). This is handy because the host principal, the KDC end of the `krb5.keytab`, is also created using kadmin(8).

A ticket must already be obtained and this ticket must be allowed to use the kadmin(8) interface in the `kadmind.acl`. See the section titled “Remote administration” in`info heimdal` for details on designing access control lists. Instead of enabling remote kadmin(8) access, the administrator can securely connect to the KDC via the local console or ssh(1), and perform administration locally using `kadmin -l`.

After installing `/etc/krb5.conf`, use `add --random-key` from the Kerberos server. This adds the server's host principal. Then, use `ext` to extract the server's host principal to its own keytab. For example:

`#` `kadmin` kadmin>`add --random-key host/myserver.example.org` Max ticket life [unlimited]: Max renewable life [unlimited]: Attributes []: kadmin>`ext host/myserver.example.org` kadmin>`exit`

Note that `ext` stores the extracted key in `/etc/krb5.keytab` by default.

If kadmind(8) is not running on the KDC and there is no access to kadmin(8) remotely, add the host principal (`host/myserver.EXAMPLE.ORG`) directly on the KDC and then extract it to a temporary file to avoid overwriting the `/etc/krb5.keytab` on the KDC, using something like this:

`#` `kadmin` kadmin>`ext --keytab=/tmp/example.keytab host/myserver.example.org` kadmin>`exit`

The keytab can then be securely copied to the server using scp(1) or a removable media. Be sure to specify a non-default keytab name to avoid overwriting the keytab on the KDC.

At this point, the server can communicate with the KDC using `krb5.conf` and it can prove its own identity with `krb5.keytab`. It is now ready for the Kerberos services to be enabled. For this example, the telnetd(8) service is enabled in `/etc/inetd.conf` and inetd(8) has been restarted with `service inetd restart`:

telnet stream tcp nowait root /usr/libexec/telnetd telnetd -a user

The critical change is that the `-a` authentication type is set to user. Refer to telnetd(8) for more details.

### 15.7.4. Kerberos Enabling a Client with Heimdal

Setting up a client computer is easy as only `/etc/krb5.conf` is needed. Securely copy this file over to the client computer from the KDC.

Test the client by attempting to use kinit(1), klist(1), and kdestroy(1) from the client to obtain, show, and then delete a ticket for the principal created above. Kerberos applications should also be able to connect to Kerberos enabled servers. If that does not work but obtaining a ticket does, the problem is likely with the server and not with the client or the KDC.

When testing a Kerberized application, try using a packet sniffer such as tcpdump(1) to confirm that the password is not sent in the clear.

Various non-core Kerberos client applications are available. The “minimal” installation in FreeBSD installs telnetd(8) as the only Kerberos enabled service.

The Heimdal port installs Kerberos enabled versions of ftpd(8), rshd(8), rcp(1), rlogind(8), and a few other less common programs. The MIT port also contains a full suite of Kerberos client applications.

### 15.7.5. User Configuration Files: `.k5login` and `.k5users`

Users within a realm typically have their Kerberos principal mapped to a local user account. Occasionally, one needs to grant access to a local user account to someone who does not have a matching Kerberos principal. For example, `tillman@EXAMPLE.ORG` may need access to the local user account `webdevelopers`. Other principals may also need access to that local account.

The `.k5login` and `.k5users` files, placed in a user's home directory, can be used to solve this problem. For example, if `.k5login` with the following contents is placed in the home directory of `webdevelopers`, both principals listed will have access to that account without requiring a shared password.:

tillman@example.org jdoe@example.org

Refer to ksu(1) for more information about `.k5users`.

### 15.7.6. Kerberos Tips, Tricks, and Troubleshooting

- When using either the Heimdal or MIT Kerberos ports, ensure that the `PATH` lists the Kerberos versions of the client applications before the system versions.

- If all the computers in the realm do not have synchronized time settings, authentication may fail. Section 30.11, “Clock Synchronization with NTP” describes how to synchronize clocks using NTP.

- MIT and Heimdal interoperate except for kadmin(8), which is not standardized.

- If the hostname is changed, the `host/` principal must be changed and the keytab updated. This also applies to special keytab entries like the `www/` principal used for Apache's `www/mod_auth_kerb`.

- All hosts in the realm must be both forward and reverse resolvable in DNS or, at a minimum, in `/etc/hosts`. CNAMEs will work, but the A and PTR records must be correct and in place. The error message for unresolvable hosts is not intuitive: Kerberos5 refuses authentication because Read req failed: Key table entry not found.

- Some operating systems that act as clients to the KDC do not set the permissions for ksu(1) to be setuid `root`. This means that ksu(1) does not work. This is not a KDC error.

- With MIT Kerberos, in order to allow a principal to have a ticket life longer than the default ten hours, use `modify_principal` at the kadmin(8) prompt to change the maxlife of both the principal in question and the `krbtgt` principal. Then the principal can use `kinit -l` to request a ticket with a longer lifetime.

- ### Note:

  When running a packet sniffer on the KDC to aid in troubleshooting while running kinit(1) from a workstation, the Ticket Granting Ticket (TGT) is sent immediately upon running kinit(1), even before the password is typed. This is because the Kerberos server freely transmits a TGT to any unauthorized request. However, every TGT is encrypted in a key derived from the user's password. When a user types their password, it is not sent to the KDC, it is instead used to decrypt the TGT that kinit(1) already obtained. If the decryption process results in a valid ticket with a valid time stamp, the user has valid Kerberos credentials. These credentials include a session key for establishing secure communications with the Kerberos server in the future, as well as the actual TGT, which is encrypted with the Kerberos server's own key. This second layer of encryption allows the Kerberos server to verify the authenticity of each TGT.

- To use long ticket lifetimes, such as a week, when using OpenSSH to connect to the machine where the ticket is stored, make sure that Kerberos `TicketCleanup` is set to `no` in `sshd_config` or else tickets will be deleted at log out.

- Host principals can have a longer ticket lifetime. If the user principal has a lifetime of a week but the host being connected to has a lifetime of nine hours, the user cache will have an expired host principal and the ticket cache will not work as expected.

- When setting up `krb5.dict` to prevent specific bad passwords from being used as described in kadmind(8), remember that it only applies to principals that have a password policy assigned to them. The format used in `krb5.dict` is one string per line. Creating a symbolic link to `/usr/share/dict/words` might be useful.

### 15.7.7. Differences with the MIT Port

The major difference between MIT and Heimdal relates to kadmin(8) which has a different, but equivalent, set of commands and uses a different protocol. If the KDC is MIT, the Heimdal version of kadmin(8) cannot be used to administer the KDC remotely, and vice versa.

The client applications may also use slightly different command line options to accomplish the same tasks. Following the instructions on the MIT Kerberos web site is recommended. Be careful of path issues: the MIT port installs into `/usr/local/` by default, and the “normal” system applications run instead of MIT versions if `PATH` lists the system directories first.

### Note:

With the FreeBSD MIT `security/krb5` port, be sure to read `/usr/local/share/doc/krb5/README.FreeBSD` installed by the port to understand why logins via telnetd(8) and `klogind` behave somewhat oddly. Correcting the “incorrect permissions on cache file” behavior requires that the `login.krb5` binary be used for authentication so that it can properly change ownership for the forwarded credentials.

The following edits should also be made to `rc.conf`:

kerberos5_server="/usr/local/sbin/krb5kdc" kadmind5_server="/usr/local/sbin/kadmind" kerberos5_server_enable="YES" kadmind5_server_enable="YES"

This is done because the applications for MIT Kerberos installs binaries in the `/usr/local` hierarchy.

### 15.7.8. Mitigating Limitations Found in Kerberos

#### 15.7.8.1. Kerberos is an All or Nothing Approach

Every service enabled on the network must be modified to work with Kerberos, or be otherwise secured against network attacks, or else the user's credentials could be stolen and re-used. An example of this would be Kerberos enabling all remote shells but not converting the POP3 mail server which sends passwords in plain text.

#### 15.7.8.2. Kerberos is Intended for Single-User Workstations

In a multi-user environment, Kerberos is less secure. This is because it stores the tickets in `/tmp`, which is readable by all users. If a user is sharing a computer with other users, it is possible that the user's tickets can be stolen or copied by another user.

This can be overcome with the `-c` command-line option or, preferably, the `KRB5CCNAME` environment variable. Storing the ticket in the user's home directory and using file permissions are commonly used to mitigate this problem.

#### 15.7.8.3. The KDC is a Single Point of Failure

By design, the KDC must be as secure as its master password database. The KDC should have absolutely no other services running on it and should be physically secure. The danger is high because Kerberos stores all passwords encrypted with the same “master” key which is stored as a file on the KDC.

A compromised master key is not quite as bad as one might fear. The master key is only used to encrypt the Kerberos database and as a seed for the random number generator. As long as access to the KDC is secure, an attacker cannot do much with the master key.

Additionally, if the KDC is unavailable, network services are unusable as authentication cannot be performed. This can be alleviated with a single master KDC and one or more slaves, and with careful implementation of secondary or fall-back authentication using PAM.

#### 15.7.8.4. Kerberos Shortcomings

Kerberos allows users, hosts and services to authenticate between themselves. It does not have a mechanism to authenticate the KDC to the users, hosts or services. This means that a trojanned kinit(1) could record all user names and passwords. Filesystem integrity checking tools like `security/tripwire` can alleviate this.

### 15.7.9. Resources and Further Information

- The Kerberos FAQ

- Designing an Authentication System: a Dialog in Four Scenes

- RFC 1510, The Kerberos Network Authentication Service (V5)

- MIT Kerberos home page

- Heimdal Kerberos home page

Prev | Up | Next
15.6. TCP Wrappers | Home | 15.8. OpenSSL

This, and other documents, can be downloaded from http://ftp.FreeBSD.org/pub/FreeBSD/doc/

For questions about FreeBSD, read the documentation before contacting <questions@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.