4.6 Client and Application Server Installation

Before a client machine or Kerberized application server can use Kerberos authentication, it must have the proper libraries, configuration files, and in some cases, service and host principals added to a local keytab file. We will limit the discussion (for now) to using the same Kerberos implementation both on the KDC and the clients. Most of the setup information below can be used to interface with a different vendor's KDC, but we will take a closer look at interoperability later in Chapter 8.

4.6.1 Unix as a Kerberos Client

There are three major steps to setting up a Unix-based Kerberos client or Kerberized application server: compiling the distribution, installing configuration files, and creating host and service principals if necessary. The first step, compiling the distribution, has already been discussed in the "Building the distribution" sections (under the appropriate heading for your chosen Kerberos implementation); follow the directions to build and install the client libraries.

Next, we'll create configuration files on each of the clients. Both MIT and Heimdal use a configuration file located in /etc/krb5.conf. This configuration file contains the name and addresses of all KDCs that the client can communicate with. Alternatively, this information can be placed in DNS, as discussed in Section 4.5. Since most Kerberos installations are still using configuration files, we'll discuss them.

We saw a simple krb5.conf file earlier, when we set up the MIT KDC above. That template still applies for clients, and in fact, the /etc/krb5.conf configuration file can be copied straight from the KDC to all of the clients. If you want to tweak the configuration file anyway, there are three stanzas that are important for client configuration: libdefaults, realms, and domain_realm.

Let's start with a sample configuration file. It should look familiar; it is the same one presented in the KDC installation section (Section 4.4):

[libdefaults]
        default_realm = WEDGIE.ORG

[realms]
        WEDGIE.ORG = {
                kdc = freebsd.wedgie.org:88
                admin_server = freebsd.wedgie.org:749
                default_domain = wedgie.org
        }

[domain_realm]
        wedgie.org = WEDGIE.ORG
        .wedgie.org = WEDGIE.ORG

The libdefaults stanza contains parameters that apply to all applications using the Kerberos libraries. The only option that you may have to tweak in this stanza is the default_realm option. This option specifies the default realm that the Kerberos libraries will use when trying to find a service principal for a given service. Normally, the Kerberos realm and DNS domain name are the same, but they can be different. If your Kerberos realm differs from the DNS domain that this machine resides in, then you should set this parameter to your Kerberos realm.

The realms stanza includes information about every Kerberos realm that this client can communicate with. Every realm that the client has to communicate with must either have an entry in the realms section on the clients' krb5.conf file or be included in the DNS as described above in Section 4.5. The only required parameter inside of a realm declaration is kdc, which gives the address and optional port number of a KDC that is authoritative for that realm. Multiple kdc declarations can be given if there are multiple KDCs serving that realm. An optional admin_server declaration lists the address and optional port number of the master KDC that handles client password changes and other administrative tasks.

The domain_realm stanza maps DNS domain names to Kerberos realm names. Whenever an application contacts a Kerberized service, it has to ask a Kerberos KDC for a ticket to that service. The Kerberos client libraries use the DNS domain name of the server to determine what Kerberos realm, and consequently, what Kerberos KDC to contact in order to request the tickets. The domain_realm stanza defines these mappings. In addition, as discussed above in Section 4.5, these mappings can be stored in DNS.

Each mapping consists of a key/value pair, where the key is a DNS domain name or hostname, and the value is the corresponding realm. In the example above, the hostname wedgie.org, as well as any hosts inside of the wedgie.org domain (note the initial dot on the second item in domain_realm) are mapped to the WEDGIE.ORG realm.

Once the configuration files are in place on all clients and application servers, we are ready to configure a sample Kerberized application: the Kerberized telnet included with both MIT and Heimdal.

Your /etc/inetd.conf file probably already contains an entry for your system's telnet daemon. If you're using an inetd replacement such as xinetd, your configuration may be in a different location with a different file format, but the concepts will remain the same. You'll want to enable the telnet server if it isn't already, and change the path to the telnet daemon so that it matches the new Kerberized telnet daemon that you installed as part of the Kerberos distribution. An example for inetd.conf to call the MIT Kerberos telnet daemon is below:

telnet  stream  tcp     nowait  root    /usr/local/sbin/telnetd telnetd

Restart your inetd and your new Kerberized telnet daemon is ready to use.

To test, you'll need to first authenticate yourself to Kerberos. Right now, we'll use kinit to manually perform this step. You can kinit from any machine that has the Kerberos distribution and configuration files installed.

% kinit jgarman
Password for jgarman@WEDGIE.ORG:

Now you should have a Ticket Granting Ticket for your realm. You can verify this by using the klist command:

% klist
Ticket cache: FILE:/tmp/krb5cc_1000
Default principal: jgarman@WEDGIE.ORG

Valid starting     Expires            Service principal
12/02/02 01:02:30  12/02/02 11:02:30  krbtgt/WEDGIE.ORG@WEDGIE.ORG


Kerberos 4 ticket cache: /tmp/tkt1000
klist: You have no tickets cached

This output is from MIT; Heimdal's klist shows similar information, but in a different format.

Now we're ready to attempt logging into our new telnet server through Kerberos authentication:

% /usr/local/bin/telnet -a freebsd.wedgie.org
Trying 192.168.0.5...
Connected to freebsd.wedgie.org (192.168.0.5).
Escape character is '^]'.
[ Kerberos V5 accepts you as ``jgarman@WEDGIE.ORG'' ]
Last login: Mon Dec  2 01:07:25 from 192.168.0.4
FreeBSD 4.7-STABLE (PII) #0: Thu Oct 17 02:30:53 GMT 2002
....

If everything works, you should see the above message that Kerberos V5 accepts you.

Note that we're using the telnet client included with your Kerberos distribution; for Heimdal Kerberos, the default location for this binary is /usr/heimdal/bin/telnet. You need to use the Kerberized telnet client in order for Kerberos authentication to work correctly. In addition, the -a option is used to tell the telnet client to automatically log us in with our previously obtained credentials. Without the -a option, the Kerberos telnet client will behave exactly the same as a traditional non-Kerberized telnet client—by asking the user for a login and password to send to the server in clear text.

If you're having trouble, the first item to check is whether you are using the correct DNS name for the telnet server in your telnet command line. If, for example, you are on the same system as the telnet server and you attempt to "telnet -a localhost," the Kerberos negotiation will fail. This is because the telnet client is attempting to acquire a service ticket for host/localhost@YOUR.REALM; you probably don't have a principal named that. (And you shouldn't!) Instead, you must use a DNS name or IP that reverse resolves to the DNS name that was used to create the host principal.

4.6.2 Mac OS X as a Kerberos Client

Mac OS X 10.2 and higher contain built-in support for Kerberos. The Kerberos included with Mac OS X is actually a modified version of the MIT Kerberos 5 distribution. As a result, the best way to approach Kerberos client functionality in Mac OS X is to simply treat it as a special case of a generic MIT Kerberos client running Unix. However, there are a few quirks and some added functionality included with the Mac OS X implementation as compared to a stock MIT Kerberos 5 distribution.

First, while Kerberos is included with the base Mac OS X distribution, it is recommended that administrators install the MIT Kerberos Extras for Mac OS to add some of the functionality that was omitted from the Apple distribution (http://web.mit.edu/macdev/Development/MITKerberos/Common/Documentation/osx-kerberos-extras.html). These Extras add support for Carbon-based applications that use the CFM Kerberos libraries, as well as placing an alias to the Kerberos graphical ticket utility included with Mac OS X into a more suitable location (namely, /Applications/Utilities).

The location of the configuration file is different than the traditional MIT file location. Instead of /etc/krb5.conf, the Kerberos configuration file is located in /Library/Preferences/edu.mit.kerberos, which follows more closely the naming conventions in Mac OS X. Unfortunately, there is currently no graphical utility included with Mac OS X to create or edit this file. Nonetheless, the contents of the file are the same as the krb5.conf file, so you can simply copy a working krb5.conf file from a Unix machine into the edu.mit.kerberos Preferences file.

GUI users need not despair, however, since Mac OS X contains a graphical credential cache and ticket manager application. This application is located in /System/Library/CoreServices/Kerberos, and if you've installed the Kerberos Extras, there is a link to it located in /Applications/Utilities. When that application is launched, the GUI credential cache window appears, shown in Figure 4-7.

Figure 4-7. Mac OS X graphical Kerberos ticket manager

In addition, if there are valid tickets in the credential cache, the Kerberos application's dock icon shows the remaining lifetime of the active principal's TGT, in hours and minutes, shown in Figure 4-8.

Figure 4-8. Mac OS X Kerberos dock icon, showing remaining TGT lifetime in hours and minutes

This GUI application segues into the major difference between Mac OS X's implementation of Kerberos and the stock MIT Kerberos 5 distribution. To ensure consistent behavior of Kerberos applications running on Mac OS X, whether those applications are native Carbon or Cocoa apps or older OS 9 applications running under the Classic environment, Mac OS X uses a memory-based credential cache as opposed to a file-based credential cache.

In addition, the Mac OS X Kerberos libraries and applications support multiple client principals, and switching between these principals. Traditionally, with MIT Kerberos, if you wish to be authenticated in two or more realms at the same time, you have to manually swap credential cache files by setting the KRB5CCACHE environment variable to a different file for each principal, and then running kinit with the appropriate credential cache for each principal. Then, you have to remember to change the KRB5CCACHE environment variable to the appropriate credential cache for the principal you wish to use before starting a Kerberized client program.

Obviously, this is a rather convoluted procedure, and since the Mac OS X Kerberos libraries already use a memory-based credential cache instead of a file-based credential cache, the solution is simple. The memory-based credential cache includes support for multiple credential caches that are managed automatically by the Kerberos libraries.

The initial credential cache in Mac OS X is named "API:Initial default ccache" and additional credential caches start their naming at "API:0", where the zero indicates the sequence in which the caches were created for this user. The active principal is underlined in the GUI Kerberos application, and the Kerberos dock menu has a checkmark next to the active principal. Switching active principals in the Kerberos application is as easy as using the dock menu to select the appropriate principal, or clicking on the principal in the Kerberos application and selecting "Make user active". In addition, Mac OS X includes a command-line utility, kswitch, that can switch between active principals, either by specifying the name of the credential cache or the client principal associated with the credential cache. Also note that destroying the current credential cache will not only delete the current credential cache but also automatically switch the active principal to the next most recently used principal, if one exists.

Of course, if you prefer the traditional Unix CLI Kerberos tools, those are available in Mac OS X as well. The kinit, klist, and other command-line Kerberos tools are available in Mac OS X and work very similarly to their MIT counterparts, with slightly different semantics to support the credential switching and memory-based credential cache capabilities. The kinit program will create a new credential cache if a user already has tickets for one principal and acquires tickets for another principal, unlike MIT kinit which would destroy the tickets for the previous principal and store the tickets for the new principal. In addition, the klist command is extended with an -A option, which lists the tickets for all credential caches associated with the currently logged in user. For example, here's a user who has tickets for both the jgarman@WEDGIE.ORG and tdurden@SAMPLE.COM principals:

> klist -A
Kerberos 5 ticket cache: 'API:Initial default ccache'
Default Principal: jgarman@WEDGIE.ORG
Valid Starting     Expires            Service Principal
05/29/03 09:23:41  05/29/03 19:23:41  krbtgt/WEDGIE.ORG@WEDGIE.ORG
05/29/03 09:23:42  05/29/03 19:23:41  imap/freebsd.wedgie.org@WEDGIE.ORG

-------------------------------------------------------------------------------
Kerberos 5 ticket cache: 'API:0'
Default Principal: tdurden@SAMPLE.COM
Valid Starting     Expires            Service Principal
05/29/03 15:12:38  05/30/03 01:12:39  krbtgt/SAMPLE.COM@SAMPLE.COM
> kswitch -p tdurden@SAMPLE.COM
> klist
Kerberos 5 ticket cache: 'API:0'
Default Principal: tdurden@SAMPLE.COM
Valid Starting     Expires            Service Principal
05/29/03 15:12:38  05/30/03 01:12:39  krbtgt/SAMPLE.COM@SAMPLE.COM

The command-line telnet client that is shipped with OS X has Kerberos support compiled by default. Therefore, once you have a Kerberos configuration file installed and you've logged into Kerberos, either through kinit or through the graphical Kerberos login program, you can use the standard Unix telnet command (with the -a option, as shown above) to use Kerberos authentication to log into a Kerberized telnet server.

Graphical Mac OS X applications such as Mail, Fetch, and Eudora also include Kerberos support. Once the Kerberos preferences file is in place, graphical Classic Mac OS and native Mac OS X applications will automatically launch the GUI Kerberos login application when necessary. Note that Carbon-based applications require the CFM Kerberos libraries to be installed from the Kerberos Extras package mentioned earlier before Kerberos support will function in these applications. We'll discuss how to require valid Kerberos credentials to log into a Mac OS X box in Chapter 7.

4.6.3 Windows as a Kerberos Client

If a Windows 2000/XP/2003 host is part of a Windows domain, then there is no extra work required to implement Kerberos-based login and Windows services that use Kerberos for authentication. However, for mixed environments where Windows clients will also be connecting to Kerberized services running on Unix hosts, you'll want to install the MIT Kerberos for Windows distribution on your Windows clients.

We'll explore the possibilities and implementation details of a mixed Windows/Unix Kerberos environment later. For now, let's take a look at how to install the Kerberos for Windows distribution from MIT, and some of the applications that come bundled with it.

First, retrieve the latest Kerberos for Windows distribution from the MIT Kerberos home page located at http://web.mit.edu/kerberos/www/, if you're a U.S. or Canadian citizen. Unfortunately the Cryptography Publishing Project does not currently distribute the MIT Kerberos for Windows binary distribution for overseas users. The current non-beta version as of this writing is Kerberos for Windows 2.1.2. The Kerberos for Windows distribution is packaged as several Zip files, so ensure that WinZip or some other unarchiver is installed.

The only required distribution is the main binary distribution. Another distribution that may need to be installed is the extra redistributable components—if you receive errors about missing DLLs, the Microsoft redistributable components distribution needs to be installed. Each distribution contains a rather deep directory structure, starting with a directory named with the distribution name. If you're installing multiple distributions, you'll have to manually copy the binaries and DLLs installed by the other distributions to the main distribution's rel directory.

To make the Kerberos libraries available to all Windows applications, copy the Kerberos DLLs to your Windows SYSTEM32 directory:

C:\krb5>copy comerr32.dll gssapi32.dll kclnt32.dll krb5_32.dll krb5cc32.dll %SystemRoot%\SYSTEM32

You'll also need to create a krb5.ini configuration file. This file has the same syntax as the /etc/krb5.conf file on Unix systems, so copying the krb5.conf file over from a Unix system in your Kerberos realm will suffice. Ensure that the krb5.ini file is in the SYSTEM32 directory as well so that all applications can access it. Note that if there is a krb5.ini file in the application's directory as well, it will take precedence over the system-wide file and may cause problems.

The MIT Kerberos for Windows distribution enables its memory-based credential cache by default, but also retains support for the older style, file-based credential caches. The in-memory cache support has the advantage of not exposing users' Kerberos credentials to the filesystem. Note that Kerberos credential cache, while now memory-based, is separate from the internal Windows credential cache, maintained by the LSA (Local Security Authority). The LSA cache contains, among other things, the Kerberos TGT for the currently logged in user, as well as any service tickets that were obtained through the Windows SSPI interface. To bridge this gap between the MIT and LSA credential caches, MIT Kerberos now includes a program, ms2mit, to copy TGTs out of the LSA cache into the MIT credential cache. This program, when run, will produce no output but should copy the Ticket Granting Ticket from your Windows LSA cache into the MIT credential cache.

However, there are still circumstances where a manual Kerberos login is appropriate, and MIT provides a graphical Kerberos credential cache management utility called leash32 that allows users to acquire and delete Kerberos tickets from the MIT credential cache. Leash32 also allows users to view their current Kerberos tickets graphically. The leash32 application is shown in Figure 4-9.

Figure 4-9. MIT Kerberos for Windows leash32 application

The MIT distribution also contains the traditional command-line utilities kinit, klist, and kdestroy, which act just like their Unix counterparts. In addition, all applications using MIT Kerberos for Windows honor the KRB5CCNAME environment variable to specify alternative credential cache locations.