14.5. Kerberos

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

Kerberos is a network authentication protocol which was originally created by the Massachusetts Institute of Technology (MIT) as a solution to network security problems. The Kerberos protocol uses strong cryptography so that both a client and server can prove their identity over an insecure network. Kerberos can be described as an identity-verifying proxy system and 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 or auditing functions. It is recommended that Kerberos be used with other security methods which provide authorization and audit services.

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. MIT 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. In FreeBSD, MIT Kerberos is available as the security/krb5 package or port. Heimdal Kerberos was explicitly developed outside of the US to avoid export regulations. The Heimdal Kerberos distribution is available as the security/heimdal package or port, and a minimal installation is included in the base FreeBSD install.

This section provides a guide on how to set up Kerberos using the Heimdal distribution included in FreeBSD.

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


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.5.1. 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 a KDC requires few computing resources, a dedicated machine acting only as a KDC is recommended for security reasons.

To begin setting up a KDC, add these lines to /etc/rc.conf:


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

    default_realm = EXAMPLE.ORG
	kdc = kerberos.example.org
	admin_server = kerberos.example.org
    .example.org = EXAMPLE.ORG

In this example, the KDC will use the fully-qualified hostname kerberos.example.org. Add a CNAME entry to the DNS zone file if the KDC has a different hostname than that specified in /etc/krb5.conf.

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

      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


In order for clients to be able to find the Kerberos services, the KDC 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 (users and hosts) 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 and enter a password:

# kstash
Master key: xxxxxxxx
Verifying password - Master key: xxxxxxxx

Once the master key has been created, initialize the database using kadmin -l. This option instructs kadmin 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 prompt, use init to create the realm's initial database:

# kadmin -l
kadmin> init EXAMPLE.ORG
Realm max ticket life [unlimited]:

Lastly, while still in kadmin, 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 prompt to see the available options.

kadmin> add tillman
Max ticket life [unlimited]:
Max renewable life [unlimited]:
Attributes []:
Password: xxxxxxxx
Verifying password - Password: xxxxxxxx

Next, start the KDC services by running service kerberos start and service kadmind start. 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 that was just created from the command-line of the KDC:

% 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 temporary ticket can be revoked when the test is finished:

% kdestroy

14.5.2. Configuring a Server to Use Kerberos

To configure a server to use Kerberos authentication, copy /etc/krb5.conf from the KDC to the server in a secure fashion, such as scp(1), or physically via removable media.

Next, create /etc/krb5.keytab on the server. 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. This is handy because the host principal, the KDC end of the krb5.keytab, is also created using kadmin.

A ticket must first be obtained and this ticket must be allowed to use the kadmin 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 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:

# 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 server's host principal directly on the KDC and then extract it to a temporary file to avoid overwriting the /etc/krb5.keytab on the KDC:

# 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.5.3. Configuring a Client to Use Kerberos

To configure a client to use Kerberos, securely copy /etc/krb5.conf to the client computer from the KDC.

Test the client by using kinit, klist, and kdestroy from the client to obtain, show, and then delete an existing ticket for the principal. 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 to confirm that the password is not sent in the clear.

Various Kerberos client applications are available. FreeBSD installs telnetd as the only Kerberos enabled service. The Heimdal package or port installs Kerberos enabled versions of ftpd, rshd, rcp, rlogind, and a few other less common programs. The MIT port contains a full suite of Kerberos client applications.

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 the following .k5login is placed in the home directory of webdevelopers, both principals listed will have access to that account without requiring a shared password.:


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

14.5.4. MIT Differences

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

Client applications may also use slightly different command line options to accomplish the same tasks. Following the instructions at http://web.mit.edu/Kerberos/www/ is recommended. Be careful of path issues: the MIT port installs into /usr/local/ by default, and the FreeBSD system applications run instead of the MIT versions if PATH lists the system directories first.


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


14.5.5. Kerberos Tips, Tricks, and Troubleshooting

When configuring and troubleshooting Kerberos, keep the following points in mind:

  • When using either Heimdal or MIT Kerberos, 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.

  • 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, exist 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 to be setuid root. This means that ksu does not work. This is a permissions problem, not a KDC error.

  • With MIT Kerberos, 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. The principal can then use kinit -l to request a ticket with a longer lifetime.

  • When running a packet sniffer on the KDC to aid in troubleshooting while running kinit from a workstation, the Ticket Granting Ticket (TGT) is sent immediately, 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 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 when using OpenSSH to connect to the machine where the ticket is stored, make sure that Kerberos TicketCleanup is set to no in /etc/ssh/sshd_config. Otherwise, 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.5.6. Mitigating Kerberos Limitations

Since Kerberos is an all or nothing approach, every service enabled on the network must either be modified to work with Kerberos or be otherwise secured against network attacks. This is to prevent user credentials from being stolen and re-used. An example is when Kerberos is enabled on all remote shells but the non-Kerberized POP3 mail server sends passwords in plain text.

Kerberos is intended for single-user workstations. In a multi-user environment, Kerberos is less secure as it stores the tickets in /tmp, which is readable by all users. If a user is sharing a computer, it is possible that the user's tickets can be stolen or copied by another user.

This can be overcome with kinit -c 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.

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.

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.

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 could record all user names and passwords. File system integrity checking tools like security/tripwire can alleviate this.

14.5.7. Access Issues with Kerberos and ssh

Kerberos is an excellent authentication protocol, but there are bugs in the Kerberized versions of telnet and rlogin that make them unsuitable for dealing with binary streams. By default, Kerberos does not encrypt a session unless -x is used, whereas ssh encrypts everything.

While ssh works well, it forwards encryption keys by default. This introduces a security risk to a user who uses ssh to access an insecure machine from a secure workstation. The keys themselves are not exposed, but ssh installs a forwarding port for the duration of the login. If an attacker has broken root on the insecure machine, he can utilize that port to gain access to any other machine that those keys unlock.

It is recommended that ssh is used in combination with Kerberos whenever possible for staff logins as it can be compiled with Kerberos support. This reduces reliance on potentially exposed SSH keys while protecting passwords via Kerberos. Keys should only be used for automated tasks from secure machines as this is something that Kerberos is unsuited to. It is recommended to either turn off key-forwarding in the SSH configuration, or to make use of from=IP/DOMAIN in authorized_keys to make the key only usable to entities logging in from specific machines.

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