14.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:

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.

14.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.

14.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

14.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 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 ininfo 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.

14.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.

14.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.

14.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 28.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.

14.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_flags=""
kerberos5_server_enable="YES"
kadmind5_server_enable="YES"

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

14.7.8. Mitigating Limitations Found in Kerberos

14.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.

14.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.

14.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.

14.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.

14.7.9. Resources and Further Information

All FreeBSD documents are available for download at http://ftp.FreeBSD.org/pub/FreeBSD/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.