10.7 Kerberos5

10.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 the program (Kerberos telnet, for example). 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, as such it has historically been affected by US export regulations. The MIT Kerberos is available as a port (security/krb5). Heimdal Kerberos is another version 5 implementation, and was explicitly developed outside of the US to avoid export regulations (and is thus often included in non-commercial UNIX® variants). The Heimdal Kerberos distribution is available as a port (security/heimdal), and a minimal installation of it is included in the base FreeBSD install.

In order to reach the widest audience, these instructions assume the use of the Heimdal distribution included in FreeBSD.

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

Note that 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 your /etc/rc.conf file contains the correct settings to act as a KDC (you may need to adjust paths to reflect your own system):

kerberos5_server_enable="YES"
kadmind5_server_enable="YES"
kerberos_stash="YES"

Next we will set up your Kerberos config file, /etc/krb5.conf:

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

Note that this /etc/krb5.conf file implies that your KDC will have the fully-qualified hostname of kerberos.example.org. You will need to add a CNAME (alias) entry to your zone file to accomplish this if your KDC has a different hostname.

Next we will create the Kerberos database. This database contains the keys of all principals encrypted with a master password. You are not required to remember this password, it will be stored in a file (/var/heimdal/m-key). To create the master key, run kstash and enter a password.

Once the master key has been created, you can initialize the database using the kadmin program with the -l option (standing for ``local''). This option instructs kadmin to modify the database files directly rather than going through the kadmind network service. This handles the chicken-and-egg problem of trying to connect to the database before it is created. Once you have the kadmin prompt, use the init command to create your realms initial database.

Lastly, while still in kadmin, create your first principal using the add command. Stick to the defaults options for the principal for now, you can always change them later with the modify command. Note that you can use the ? command at any 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

Now it is time to start up the KDC services. Run /etc/rc.d/kerberos start and /etc/rc.d/kadmind start to bring up the services. Note that you won't have any kerberized daemons running at this point but you should be able to confirm the that the KDC is functioning by obtaining and listing a ticket for the principal (user) that you just created from the command-line of the KDC itself:

%k5init tillman
      tillman@EXAMPLE.ORG's Password:

      %k5list
      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
              Aug 27 15:37:58  Aug 28 01:37:58  krbtgt/EXAMPLE.ORG@EXAMPLE.ORG

      v4-ticket file: /tmp/tkt500
      k5list: No ticket file (tf_util)

10.7.3 Kerberos enabling a server with Heimdal services

First, we need a copy of the Kerberos configuration file, /etc/krb5.conf. To do so, simply copy it over to the client computer from the KDC in a secure fashion (using network utilities, such as scp(1), or physically via a floppy disk).

Next you need a /etc/krb5.keytab file. This is the major difference between a server providing Kerberos enabled daemons and a workstation -- the server must have a keytab file. This file contains the servers 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. This explicitly means that transferring it via a clear text channel, such as FTP, is a very bad idea.

Typically, you transfer to the keytab to the server using the kadmin program. This is handy because you also need to create the host principal (the KDC end of the krb5.keytab) using kadmin.

Note that you must have already obtained a ticket and that this ticket must be allowed to use the kadmin interface in the kadmind.acl. See the section titled ``Remote administration'' in the Heimdal info pages (info heimdal) for details on designing access control lists. If you do not want to enable remote kadmin access, you can simply securely connect to the KDC (via local console, ssh(1) or Kerberos telnet(1)) and perform administration locally using kadmin -l.

After installing the /etc/krb5.conf file, you can use kadmin from the Kerberos server. The add --random-key command will let you add the servers host principal, and the ext command will allow you to extract the servers 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 the ext command (short for ``extract'') stores the extracted key in /etc/krb5.keytab by default.

If you do not have kadmind running on the KDC (possibly for security reasons) and thus do not have access to kadmin remotely, you can add the host principal (host/myserver.EXAMPLE.ORG) directly on the KDC and then extract it to a temporary file (to avoid over-writing the /etc/krb5.keytab on the KDC) using something like this:

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

You can then securely copy the keytab to the server computer (using scp or a floppy, for example). Be sure to specify a non-default keytab name to avoid over-writing the keytab on the KDC.

At this point your server can communicate with the KDC (due to its krb5.conf file) and it can prove its own identity (due to the krb5.keytab file). It is now ready for you to enable some Kerberos services. For this example we will enable the telnet service by putting a line like this into your /etc/inetd.conf and then restarting the inetd(8) service with /etc/rc.d/inetd restart:

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

The critical bit is that the -a (for authentication) type is set to user. Consult the telnetd(8) manual page for more details.

10.7.4 Kerberos enabling a client with Heimdal

Setting up a client computer is almost trivially easy. As far as Kerberos configuration goes, you only need the Kerberos configuration file, located at /etc/krb5.conf. Simply securely copy it over to the client computer from the KDC.

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

When testing an application like telnet, try using a packet sniffer (such as tcpdump(1)) to confirm that your password is not sent in the clear. Try using telnet with the -x option, which encrypts the entire data stream (similar to ssh).

The core Kerberos client applications (traditionally named kinit, klist, kdestroy, and kpasswd) are installed in the base FreeBSD install. Note that FreeBSD versions prior to 5.0 renamed them to k5init, k5list, k5destroy, k5passwd, and k5stash (though it is typically only used once).

Various non-core Kerberos client applications are also installed by default. This is where the ``minimal'' nature of the base Heimdal installation is felt: telnet is the only Kerberos enabled service.

The Heimdal port adds some of the missing client applications: Kerberos enabled versions of ftp, rsh, rcp, rlogin, and a few other less common programs. The MIT port also contains a full suite of Kerberos client applications.

10.7.5 User configuration files: .k5login and .k5users

Users within a realm typically have their Kerberos principal (such as tillman@EXAMPLE.ORG) mapped to a local user account (such as a local account named tillman). Client applications such as telnet usually do not require a user name or a principal.

Occasionally, however, you want 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 users home directory, can be used similar to a powerful combination of .hosts and .rhosts, solving this problem. For example, if a .k5login with the following contents:

tillman@example.org
    jdoe@example.org

Were to be placed into the home directory of the local user webdevelopers then both principals listed would have access to that account without requiring a shared password.

Reading the man pages for these commands is recommended. Note that the ksu man page covers .k5users.

10.7.6 Kerberos Tips, Tricks, and Troubleshooting

• When using either the Heimdal or MIT Kerberos ports ensure that your PATH environment variable lists the Kerberos versions of the client applications before the system versions.

• Is your time in sync? Are you sure? If the time is not in sync (typically within five minutes) authentication will fail.

• MIT and Heimdal inter-operate nicely. Except for kadmin, the protocol for which is not standardized.

• If you change your hostname, you also need to change your host/ principal and update your keytab. This also applies to special keytab entries like the www/ principal used for Apache's www/mod_auth_kerb.

• All hosts in your realm must be resolvable (both forwards and reverse) in DNS (or /etc/hosts as a minimum). CNAMEs will work, but the A and PTR records must be correct and in place. The error message isn't very intuitive: ``Kerberos5 refuses authentication because Read req failed: Key table entry not found''.

• Some operating systems that may being acting as clients to your KDC do not set the permissions for ksu to be setuid root. This means that ksu does not work, which is a good security idea but annoying. This is not a KDC error.

• With MIT Kerberos, if you want to allow a principal to have a ticket life longer than the default ten hours, you must use modify_principal in kadmin to change the maxlife of both the principal in question and the krbtgt principal. Then the principal can use the -l option with kinit to request a ticket with a longer lifetime.

• Note: If you run a packet sniffer on your KDC to add in troubleshooting and then run kinit from a workstation, you will notice that your TGT is sent immediately upon running kinit -- even before you type your password! The explanation is that the Kerberos server freely transmits a TGT (Ticket Granting Ticket) to any unauthorized request; however, every TGT is encrypted in a key derived from the user's password. Therefore, when a user types their password it is not being sent to the KDC, it is being 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 ticket-granting ticket, which is actually encrypted with the Kerberos server's own key. This second layer of encryption is unknown to the user, but it is what allows the Kerberos server to verify the authenticity of each TGT.

• You have to keep the time in sync between all the computers in your realm. NTP is perfect for this. For more information on NTP, see Section 19.12.

• If you want to use long ticket lifetimes (a week, for example) and you are using OpenSSH to connect to the machine where your ticket is stored, make sure that Kerberos TicketCleanup is set to no in your sshd_config or else your tickets will be deleted when you log out.

• Remember that host principals can have a longer ticket lifetime as well. If your user principal has a lifetime of a week but the host you are connecting to has a lifetime of nine hours, you will have an expired host principal in your cache and the ticket cache will not work as expected.

• When setting up a krb5.dict file to prevent specific bad passwords from being used (the manual page for kadmind covers this briefly), remember that it only applies to principals that have a password policy assigned to them. The krb5.dict files format is simple: one string per line. Creating a symbolic link to /usr/share/dict/words might be useful.

10.7.7 Differences with the MIT port

The major difference between the MIT and Heimdal installs relates to the kadmin program which has a different (but equivalent) set of commands and uses a different protocol. This has a large implications if your KDC is MIT as you will not be able to use the Heimdal kadmin program to administer your KDC remotely (or vice versa, for that matter).

The client applications may also take slightly different command line options to accomplish the same tasks. Following the instructions on the MIT Kerberos web site (http://web.mit.edu/Kerberos/www/) is recommended. Be careful of path issues: the MIT port installs into /usr/local/ by default, and the ``normal'' system applications may be run instead of MIT if your PATH environment variable lists the system directories first.

10.7.8 Mitigating limitations found in Kerberos

10.7.9 Resources and further information

• The Kerberos FAQ

• Designing an Authentication System: a Dialogue in Four Scenes

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

• MIT Kerberos home page

• Heimdal Kerberos home page