2.4. Kerberos

Kerberos is the preferred method for pretty much every directory service on the market to supplement LDAPv3, supplying enhanced password features, single sign-on, or both. Mac OS X is no different and the Kerberos client plays well either in its own Open Directory environments or in environments managed by other solutions. Mac OS X actually has a Kerberos Key Distribution Center (KDC) built into every single computer, used for securing peer-to-peer communications.

Managing Kerberos on a Mac OS X computer is mostly handled for you. There is very little to do in most environments. When you log into the first Kerberised service, be it an initial authentication into a Mac OS X client or via AFP to a SharePoint, at that initial authentication screen you will be authenticating into a Kerberos realm and will then not have to enter a password to access other services that are trusted by the realm. Beyond the basic realm configuration, most of the tools for Kerberos are often used for mass deployment of settings, manual configuration when those settings don't work correctly, and post deployment troubleshooting.

To control Kerberos using the GUI, you will use the Kerberos.app utility, which shipped with 10.5. Unfortunately, the Kerberos Ticket Viewer application was replaced in Snow Leopard with the "Ticket Viewer" Application, which is far more limited. The two can be seen side by side in Figure 2-25. Each respective utility is accessed through the Keychain Access menu of Keychain Access (which is located at /Applications/Utilities). You can also access each directly in the /System/Library/CoreServices/ directory. The 10.6 Ticket Viewer Application does not have any functionality to modify REALM configuration, and all edits must be made by hand, as discussed later in this section. Alternatively, you can copy the utility from a 10.5 install, and it will run in 10.6.

Once Kerberos.app has been opened, you can use it to browse the tickets (remember from Chapter 1 that a ticket is provided by the KDC based on the Ticket Granting Ticket). Using the toolbar, you can establish a connection to a new realm, renew tickets, Destroy tickets, get more information on tickets, and change the password associated with a ticket. In regard to per-user Kerberos ticket management, the Kerberos Ticket Viewer offers a one-stop shop.

In order to join a realm, click on the New button in the toolbar. As you can see in Figure 2-26, you'll now be prompted for an account name, a realm name, and a password. If the realm information is cached or has been supplied via DNS, then you will be able to select the realm from the Realm: drop-down menu.

Kerberos.app and Ticket Viewer are fairly limited in what they can do. There is no interface for managing service principles and each option has very few parameters, whereas with the command line there are a plethora of options and parameters. For example, to list the tickets the current user has cached, you can use the klist command:

[helyx:˜] hunterbj% klist
Kerberos 5 ticket cache: 'API:Initial default ccache'
Default principal: hunterbj@LBC

ValidStarting     Expires            Service  Principal
08/19/09 20:27:51  08/20/09 06:27:51  krbtgt/LBC@LBC
         renew until 08/26/09 20:27:51
08/19/09 20:27:54  08/20/09 06:27:51  host/hax.lbc@LBC
         renew until 08/26/09 20:27:51
08/19/09 20:28:23  08/20/09 06:27:51  vnc/mira.lbc@LBC
         renew until 08/26/09 20:27:51

As seen, the klist output is pretty basic and easy to read. You can see what I have by Ticket Granting ticket through the presence of the krbtgt/LBC@LBC service principal. You can also see that I have a host principal (used for ssh) and a vnc principal (used by OS X Screen Sharing).The klist command also has a variety of options as follows:

• −5: only display Kerberos 5-based tickets

• -4: only display Kerberos 4-based tickets

• -a: show a list of addresses

• -A: list all of the available tickets

• -c: show cached tickets

• -e: also display the encryption type of the session key

• -f: also list any flags for tickets, like -F for forwardable, -f for forwarded, -I for invalid, etc.)

• -k: list keys in the keytab file

• -K: show encryption keys from the keytab file

• -t: include timestamps in the output

• -n: show IP addresses

• -s: run silently, useful for a sanity check in a script to verify that the ticket cache is actually present

The kinit command can be used to initiate authentication into a realm, thereby generating and caching a ticket-granting ticket. In its most basic form, kinit can be called with no arguments, and will by default try to obtain a TGT for your current user in the machines default realm, as configured in the client's edu.mit.kerberos file. Alternatively, you can specify a specific username and realm to authenticate as:

[helyx:˜] hunterbj% kinit -V hunterbj
Please enter the password for hunterbj@LBC:
Authenticated via Kerberos v5.  Placing tickets in cache 'API:Initial default ccache'
[helyx:˜] hunterbj% klist
Kerberos 5 ticket cache: 'API:Initial default ccache'
Default principal: hunterbj@LBC

Valid Starting     Expires            Service Principal
08/19/09 22:01:29  08/20/09 08:01:29  krbtgt/LBC@LBC
        renew until 08/26/09 22:01:28

Additional options for the kinit command include the following:

• -V: verbose output

• -l: define the lifetime of the ticket when obtaining it

• -r: define how long a ticket is renewable

• -s: include a start time (and therefore caches a postdated ticket)

• -f : use forwardable tickets

• -F: do not use forwardable tickets

• -p: use proxiable tickets

• -P: do not use proxiable tickets

• -a: request a ticket with the host's address

• -A: request ticket without a defined address

• -v: validate a ticket in the keytab against the KDC

• -R: renew a ticket

• -k: obtain a key from a key in the local keytab file (cache) rather than from a live server

• -S: include the service name to use when obtaining ticket-granting tickets

The kdestroy command is fairly straightforward, with far fewer options than kinit—but then it has a specific task to delete tickets. The options are primarily in regard to defining which tickets to delete:

• -a or -A: destroy all tickets

• -c: name of cache to delete

• -p: name of principal to delete

• -q: run quietly (without feedback to the command line)

There are two other commands worth noting: kpasswd and kswitch. The kpasswd command can be used to change a principal's password. The kpasswd command prompts you for both your old and your new password. This can be useful, for example, if you are using an Active Directory environment or troubleshooting why users are unable to reset their own passwords. The kswitch command sets the cache for the default system.

There are also a number of files used to track various Kerberos statuses, caches, and settings. For example, the /Library/Preferences/DirectoryService/DSLDAPv3PlugInConfig.plist property list file maintains a list of all of the service principles created when a user of the host authenticates into a realm.

The keytab file is perhaps the most critical file on an operating system to secure. Kerberos uses a keytab file to store pairs of Kerberos principals and their corresponding DES keys. In Mac OS X, the keytabfile is called krb5.keytab and is stored in the /etc directory. Much of the information in the keytab is barely readable to human eyes, much less editable. Therefore, much of the heavy lifting for the keytab will be handled using the kadmin and kadmin.local commands, and in some cases the ktutil command. The former two commands have the same options and features, with the one exception being that kadmin.local is meant to manage Kerberos on a KDC while kadmin is meant to manage Kerberos on all other hosts. The kadmin command supports in regard to utilized ciphers, password restrictions, ticket life, etc. For some example usage of the tool, see the "Troubleshooting Kerberised Services" section.

Earlier, it was mentioned that Mac OS X client acts as a KDC (it's actually an LKDC, to be more specific). The /etc/krb5.conf file can be used to show available realms. For the available realms, the krb5.conf file will show the supported encryption types of each realm along with the configuration options, mappings, rules, and location. An example of the krb5.conf file is shown in the following code:

[libdefaults]
  default_realm = KRYPTED.COM
  default_tgs_enctypes = RC4-HMAC DES-CBC-MD5 DES-CBC-CRC
  default_tkt_enctypes = RC4-HMAC DES-CBC-MD5 DES-CBC-CRC
  preferred_enctypes = RC4-HMAC DES-CBC-MD5 DES-CBC-CRC
  dns_lookup_kdc = true
[realms]
  KRYPTED.COM = {
   auth_to_local = RULE:[1:$0$1](^KRYPTED.COM\.*)s/^KRYPTED.COM/KRYPTED/
   auth_to_local = DEFAULT
  }
[appdefaults]
  pam = {
   mappings = KRYPTED\(.*) [email protected]
   forwardable = true
   validate = true
  }
  httpd = {
   mappings = KRYPTED\(.*) [email protected]
   reverse_mappings = (.*)@KRYPTED.COM KRYPTED$1
  }

The preceding file is split into three sections: [libdefaults], [realms], and [appdefaults], which respectively controls Kerberos behavior, information for a given realm, and settings per service. It is more than likely that you will not need to edit the kerb5.conf file with the exception of potentially disabling DNS utilization with Kerberos, which can help to reduce login times for domains using the .local namespace. This can be done by adding the following line into the [libdefaults] section of the configuration file:

dns_fallback = no

An OS X client utilizes a krb5.conf file, but stores it at the location: /Library/Preferences/edu.mit.Kerberos. In this file, you will also find the [realms] and [libdefaults] sections, but you will also find the [domain_realm] section, which deals with normalization and definitions of realms. The contents of a typical file are listed here:

[domain_realm]
        krypted.com = KRYPTED.COM

[libdefaults]
        default_keytab_name = /etc/opt/quest/vas/host.keytab
        default_realm = KRYPTED.COM
        default_tkt_enctypes = arcfour-hmac-md5 des-cbc-md5
        dns_fallback = yes
        dns_lookup_kdc = yes
        forwardable = true

[realms]
        KRYPTED.COM = {
                admin_server = seldon.krypted.com
                kdc = server.seldon.com:88
                kpasswd_server = seldon.krypted.com:464
        }

In the preceding, you will see another dns_fallback. If you first initiated a connection to the default_realm following setting the dns_fallback in krb5.conf, which I mentioned when discussing the krb5.conf file, this setting will be set to no; otherwise it will be set to yes, and will need to be changed if you want to disable reverse dnsenumeration. Again, only be concerned about the dns_fallback if you are seeing connectivity errors and think they are related to DNS issues (you cannot perform both a forward and reverse lookup on a realm's KDC or you are using a .local domain namespace).

You should also notice the kpasswd_server entry in the edu.mit.kerberos file, which defines what password to perform a reset against in the event of a failure. In large environments with services distributed across a number of hosts, you may find stale information here, which can also cause password change events to fail. If you do find yourself needing to make changes to this file, and the file was generated by a directory binding, know that your changes will be overridden. To prevent this, you will need to delete the lines containing the text:

# autogenerated from : /LDAPv3/myserver.com
# generation_id : 419733404

Any time you change information in your Kerberos files, you'll need to restart the Kerberos services. The Kerberos services that run on a Mac OS X client include [ ] edu.mit.Kerberos.KerberosApp, edu.mit.Kerberos.KerberosAgent, edu.mit.Kerberos.CCacheServer, and com.apple.KerberosHelper.LKDCHelper.

Each of the preceding services can be controlled using launchctl. For example, if you run the launchctl command followed by the list option, you should see the following line included somewhere in the output:

-        0        edu.mit.Kerberos.CCacheServer

In order to then stop the CCache Server, you could use the launchctl command with the stop option, followed by the name of the launchd item you would like to stop. In the case of CCache Server, it would be the following:

Launchctl -stop edu.mit.Kerberos.CCacheServer

2.4.1. Kerberising Services

After binding a client or server to a domain and joining it to a Kerberos Realm, it may be desirable to Kerberise the services that the node provides. That is to say you will configure the service in such a way that your OS X boxes will provide single-sign-on access to users with valid Ticket Granting Tickets (TGTs). The process to integrate your OS X server with your current SSO environment will vary based upon the Kerberos implementation that your company provides. For instance, in Open Directory environments, Apple provides several nifty tools which do much of the legwork for you: sso_util and krbservicesetup. For Active Directory, the dsconfigad tool can do all of the legwork as well. For other implementations, it may very well be possible to utilize some of Apple's tools. However, it might also be necessary to roll your own. In any scenario, it is necessary to have a proper edu.mit.kerberos file, as discussed in the previous section. During the Active Directory and Open Directory binding process, the Kerberos information in this file will be automatically generated for you. Until you can verify that you can obtain a ticket using kinit, or the Kerberos Ticket Viewer app, you don't want to mess around with Kerberising your services.

The easiest Directory Service SSO implementations to integrate are Apple's Open Directory and Microsoft's Active Directory. Neither are terribly difficult to pull off, but from the command line, the Active Directory tool is the most simplistic. You can use the Server Admin utility to Kerberise services for a server by selecting the Open Directory Service and selecting the General tab. If the server is bound to a Directory and detects Kerberos, you will be presented with the ability to join a server to a Kerberos REALM, as seen in Figure 2-27. Click on the Join Kerberos button to generate service principals for all supported services, and then modify their configurations to utilize the new principals for authentication.

To integrate with AD from the command line, once your OS X server has been bound you simply call dsconfigad with a single flag, -enableSSO:

sudo dsconfigad -enableSSO

For more information on Active Directory, see Chapter 3.

To integrate an OS X box with Open Directory from the command line, you can utilize the sso_util binary. This utility has a wide variety of uses, but first and foremost, it can be used to generate the appropriate service principals from the Kerberos Realm's KDC, place them in the node's local keytab, and even configure the node's services to use them. The syntax is rather basic as well and is as follows:

sudo sso_util configure -r REALM -a admin_name [-p password] service

We just feed it our REALM, a kerberos administrator's credentials, and we specify a service which will be generated. You can specify one or more of the following services afp, ftp, http, imap, pop, smtp, ssh, fcsvr, vnc, cifs, or all. When ran, the command will pretty much take care of everything for us. For example, to fully kerberise an OS X laptop to the Open Directory domain myco.com, the following syntax would be used:

sudo sso_util configure -r MYCO.COM -a diradmin all

With this syntax, you will be prompted to provide your password via secure text entry, which is preferable to potentially leaving your password in your shells history, or expose your password via ps. Alternatively, you can pass the password via the environmental variable $SSO_PASSWD_PATH.

The sso_util binary has some other uses for larger OD environments as well. For example, it has the ability for a KDC administrator to generate Kerberose principals for a specific host, at which point a lesser privileged administrator can Kerberise the services on the host side. The process starts with the KDC admin first generating the record. In this case, we will be generating a record for host mail.myco.com in our OD domain myco.com:

sudo sso_util generateconfig -r MYCO.COM -R mail.myco.com -f /LDAPv3/odserver.myco.com -U thatotheradmin -a diradmin all

The previous command will attach a secure record configuration to the computer LDAP object mail.myco.com found in the LDAP database at server odsrever.myco.com. This computer object will be found at the path /Computers/mail.myco.com. The LDAP dn for this in an OD environment is cn=mail.myco.com,cn=computers,dc=myco,dc=com. The secure record configuration is an encrypted data object stored in the computer's configData LDAP attribute. The data stored in this attribute is an encrypted string which contains the Kerberos host and service principals for the desired host. Because the service principals are very sensitive, it is recommended that you delete this entry after you have successfully kerberized a host using either Server Admin or the command that follows.

In the previous sso_util command, we specify the user that otheradmin as a delegate admin. That user can now run the sso_util command from the new server, and complete the Kerberisation process:

sudo sso_util useconfig -R mail.myco.com -f /LDAPv3/odserver.myco.com -a thatotheradmin

While the main pages of sso_util specify that the tool is specifically for Open Directory, it's most basic functions provided by the configure option will likely work with most vanilla Kerberos5 implementations. Even if you don't have Open Directory, this tool may still be able to automate pretty much all of the principal generation for you.

If the sso_util command doesn't work in your environment, Apple provides a lower level tool, krbservicesetup, which might work for your needs. The krbservicesetup command is actually called by sso_util and has a few downsides, but it is worth mentioning. The krbservicesetup tool can be used to configure a single service at a time, and handles Kerberos principal generation via kadmin and local service configuration. Secondly, you must specify the password as part of the command. For example, to generate a service principal for the imap service on mail.myco.com, I would use the following command:

sudo krbservicesetup -r MYCO.COM -a diradmin -p password imap imap/[email protected]

2.4.2. Troubleshooting Kerberised Services

If you've gone through the previous section about setting up Kerberised services, and for whatever reason the previous tools do not accomplish the task, then you are not completely out of luck. However you may need to go through the grueling process of principal creation and service configuration. On top of this, each service has a different method for configuration, so it becomes a bit of a black art.

The first step in troubleshooting any kerberos error is to verify that your client and server's clocks are in sync. Kerberos is notorious for this, and it only allows for a skew of five minutes. Anything beyond this and the whole system breaks down. Next, ensure that the problem is truly server oriented and verify from multiple clients that Kerberised services are not being provided.

With that out of the way, it's time to troubleshoot the server. Consider for a moment that I am configuring my imap service to provide single sign-on. From your server, first ensure that the service has a respective service principal in the server's local keytab. To do this, use the klist command with the flags -kt, ran with root privileges via sudo:

%sudo klist -kte
Keytab name: FILE:/etc/krb5.keytab
KVNO Timestamp         Principal
---- ----------------- --------------------------------------------------------
9 08/19/09 21:15:56 imap/[email protected] (Triple DES cbc mode with HMAC/sha1)
9 08/19/09 21:15:56 imap/[email protected] (ArcFour with HMAC/md5)   3 08/19/09
9 08/19/09 21:15:56 imap/[email protected] (DES cbc mode with CRC-32)
9 08/19/09 21:15:56 vnc/[email protected] (Triple DES cbc mode with HMAC/sha1)
9 08/19/09 21:15:56 vnc/[email protected] (ArcFour with HMAC/md5)   3 08/19/09
9 08/19/09 21:15:56 vnc/[email protected] (DES cbc mode with CRC-32)

(output clipped)

Looking at this output, I can see that my local keytab (/etc/krb5.keytab) does indeed contain the imap service principal, three in fact. This illustrates the default nature of Open Directory's KDC behavior, it generates three principles for each service, encrypted via des, 3des, and md5, respectively. By supporting all three encryption algorithms, the service can provide maximum compatibility.

If the necessary Kerberos principals for your service don't exist, and sso_util isn't doing its job and creating them for you, then you can create your own principles. Principal generation is done via the kadmin or kadmin.local utility. The exact procedure may vary based upon your Kerberos toolset, but the following should work with most MIT based KDC's. First, we connect to our KDC via kadmin, preferably from our new mail server:

$ sudo kadmin -r MYCO.COM -p diradmin
Authenticating as principal diradmin with password.
Password for [email protected]:
kadmin:

Next, we can run the listprincs command to see if our service principal already exists in the kdc:

>kadmin: listprincs
(output cut)
host/[email protected]
ldap/[email protected]
vnc/[email protected]
 (output cut)

We've cut the output of this command for brevity, but in large environments that command can return a long list of data. Alternatively, we can use the getprinc command to specifically query the principal we are interested in:

>kadmin:  getprinc imap/[email protected]
Principal: imap/[email protected]
Expiration date: [never]
Last password change: Wed Aug 19 21:15:56 PDT 2009
Password expiration date: [none]
Maximum ticket life: 0 days 10:00:00
Maximum renewable life: 7 days 00:00:00
Last modified: Wed Aug 19 21:15:56 PDT 2009 ([email protected])
Last successful authentication: [never]
Last failed authentication: [never]
Failed password attempts: 0
Number of keys: 3
Key: vno 9, Triple DES cbc mode with HMAC/sha1, no salt
Key: vno 9, ArcFour with HMAC/md5, no salt
Key: vno 9, DES cbc mode with CRC-32, no salt

Here we can see the principal does exist, and at the bottom, we can even see the three different encryption keys used by that principal. If this principal didn't yet exist, we could create it using kadmin's addprinc command. We specify the -randkey option to generate a random password for the principal:

>kadmin: addprinc -randkey imap/mail.myco.com
Principal "imap/[email protected]" created.

With the service principal created on the KDC, we now need to copy it to our local machines keytab file. If we ran kadmin from the local machine, this is very easy to do by using the ktadd and specifying our local keytab file at /etc/krb5.keytab:

>kadmin:  ktadd -k /etc/krb5.keytab imap/mail.myco.com
Entry for principal imap/mail.myco.com with kvno 3, encryption type Triple DES cbc mode with HMAC/sha1 added to keytab WRFILE:/etc/krb5.keytab.
Entry for principal imap/mail.myco.com with kvno 3, encryption type ArcFour with HMAC/md5 added to keytab WRFILE:/etc/krb5.keytab.
Entry for principal imap/mail.myco.com with kvno 3, encryption type DES cbc mode with CRC-32 added to keytab WRFILE:/etc/krb5.keytab.

We can now run klist -kt as root on our machine and we should see the new principals listed in our local keytab file. If we ran kadmin from a different machine, we will need to write the principals to an arbitrary file, and transfer it to the server. Be careful with this methodology though, as if the keytab file is compromised, it can be used to hack into your server. If you find yourself needing to do this, run the ktadd command, but specify a different file to export to, say /Users/admin/mail.myco.com.keytab. From here, you will need to copy the file to the server, for simplicities sake we'll say you placed the file in the same path. From the new server, we will use the ktutil command to add this keytab to our existing krb5.keytab file. ktutil is not the friendliest of commands, but the basic operations are easy enough. First, fire up the utility, and read in our new keytab file with the rkt option:

$sudo ktutil
ktutil: rkt /Users/admin/mail.myco.com.keytab

Next, we'll read in our existing keytab file at /etc/krb5.keytab:

ktutil: rkt /etc/krb5.keytab

We now have loaded both our existing principals and our new principals into memory. The next step is to write out all of the loaded principals to our local file via the wkt option:

ktutil: wkt /etc/krb5.keytab2
ktutil: quit

We have now written our keytabs to a new file /etc/krb5.keytab2. At this point we need to make it our active keytab file:

mv /etc/krb5.keytab2 /etc/krb5.keytab

We have now merged the two keytab's entries, and you can now delete the transfer mail.mycoc.com.keytab file.

Once the service principals exist both on the KDC and in the server/client's local keytab file, the pieces are in place for a successful SSO setup, and all that is left is the configuration of individual service(s). The unfortunate reality of the situation is that each service is a little bit different in this respect. Some services, such as vnc and ssh, simply search for the principal appropriate for the connection hostname. For instance, from my client if I connect via ssh to mail.myco.com, it will search for the principal host/[email protected]. However, if I ssh to the same box via its bonjour address, mail.local, it will search for the principal host/[email protected], which will typically not exist. VNC works in a similar manner.

The AFP service utilizes a specific principle specified via its preference file found at /Library/Preferences/com.apple.AppleFileServer.plist. There are two specific keys that the AFP server uses for SSO: kerberosPrincipal and authenticationMode. The first attribute is simply the string text of the principal, afpserver/[email protected]. The second attribute defines the types of authentication. This attribute will contain one of three values: standard_and_kerberos, standard, or kerberos. The three values are fairly self explanatory. We recommend the first of the three, standard_and_kerberos. In this configuration, the AFP server will default to Kerberos, and if that fails for whatever reason, will revert to its standard authentication method: Diffie-Hellman Exchange (DHX).

The latter option can be configured for the AFP Service by using the Server Admin utility, as shown in Figure 2-28. Noticably absent from that picture is a field to define the Kerberose principle. To set that, you can use the defaults command to modify the service's plist, and then restart the service to read in the new setting (active transfers will be interrupted):

sudo defaults write /Library/Preferences/com.apple.AppleFileServer kerberosPrincipal 'afpserver/[email protected]'
sudo killall AppleFileServer

Numerous other services have similar authentication selections to that shown in Figure 2-28: FTP, iCal, iChat, Web, and Xgrid. For each of these services, Kerberos authentication is enabled by default.

The mail service, like the ssh service, utilizes gssapi based authentication, which provides a more standardized interface over the Kerberos API for authentication services, but commonly utilizes Kerberos as it's actual authentication mechanism. The easiest way to enable Kerberos for mail services is via the Server Admin application. As shown in Figure 2-29, Kerberos authentication can be enabled individually for each protocol, SMTP, IMAP, and POP. Once again, it is recommended that you enable a non-Kerberos fallback authentication, unless security policies require it.

After ensuring that your service is properly setup to use Kerberos, and the principals exist in the KDC and the local keytab, you should have a functional SSO-friendly service. If this still is not the case, then you'll have to resort to the logging facilities provided by each service. Keep in mind that the number one killer of Kerberos is its heavy reliance on synchronized clocks, so always check that your client and server's clocks are in sync.