Kerberos Part 2

If you just finished reading part 1, take a break. Kick back on a natural for a bit and let Kerberos sink in. Perhaps re-read the article if things are a bit fuzzy. Just a suggestion.

If you feel comfortable with Kerberos, let's now talk about how Apple has actually implemented it. As I mentioned before Apple now includes a full kdc in OS X 10.3 Panther Server. It will act, walk and talk like a standard MIT Kerberos v5 kdc to anyone who wants to talk with it. Of course if Apple just stopped there, it wouldn't really be Apple would it?

Apple took a standard MIT Kerberos distribution, made sure that it stayed compatible with other MIT Kerberos systems and added on a few bits that are almost as ingenious as Kerberos itself.

In this part of the series, I'll walk through Kerberos as it is implemented on OS X, covering what Apple has added and any major differences between what's on OSX and what's on other MIT Kerberos systems.



1. The kdc

If you set up your OS X Server as an Open Directory Master, and everything is copacetic with your DNS, you will automagically become a Kerberos Key Distribution Center (kdc). This process is so automatic that you literally won't see it happen. There is no "Kerberos" button or any GUI configuration for it. It's just there. It's so stealthy that the only indication from the admin tools that it's actually running is a single entry in the Open Directory section of Server Admin that says whether or not the kdc is running.

On a standard MIT Kerberos system, you need to do a bit of work to get it up and running. After you have it installed, since it usually doesn't come pre-built on systems, you need to initialize the kdc's password database and then create principles for the kdc, any services you might be hosting, and then start in on creating the users' principles.

It's with the user principles that you have to begin veering from the simple stuff.

Kerberos only handles user password. It doesn't store any information about the user whatsoever. This means that even if you are running Kerberos, you will still need to keep your user records in a directory service of some sort. This can be almost anything, ie. NIS, LDAP, MySQL, or even flat files, but you have to have it. Additionally not all services understand Kerberos. For example it can be a real pain in the butt to support Kerberos authentication for mail services.

All of this means that you'll have to set up a directory service in addition to Kerberos. To allow non-kerberized services to authenticate you'll also have to set up either some sort of Kerberos authentication gateway, or just keep another password database.

MIT provides no easy solution to this problem. It isn't part of their feature set for Kerberos and probably never will be. To get around this most Kerberos admins have hand-crafted a collection of scripts or other mechanisms to keep the two password databases in synch. There is no real standard on doing this and it's almost guaranteed that you'll have to tweak anything you find to work for your system.

Apple has done all of this legwork for you. They built on the Password Server that made it's appearance in OS X Server 10.2 and integrated it with Kerberos and LDAP starting with 10.3. An Open Directory Master will keep all of the user records in an LDAP database and keep copies of the user's password in both the SASL Password Server and the Kerberos kdc. Changing the password with one method will change it in both databases.

When a user is created in an Open Directory system that has a kdc running they will have two authentication authorities listed with their user record. One will refer to their unique SASL Password Server ID and the other will reference their Kerberos principle. This way Open Directory knows what to do when looking for a user's password.

On OS X the kdc database is stored in /var/db/krb5kdc. This is only readable by root and contains the actual kdc database itself, some support files, and the kdc.conf file that sets up some basic configuration parameters for the kdc. The database and the config file are the same as any other MIT Kerberos system.

If your kdc is running, as it should be automatically after an OS X Server install. You can see what principles are stashed away inside the database by using the kadmin command.

On a stock install you need to be root and use

kadmin.local

Once you do a bit of configuration and get the kdamind process running you can later use just

kadmin

Either way, once you get to the kadmin prompt you can use

listprincs

to see what principles your kdc knows about.

If your kdc was never created when you set up your server, this is probably because you are either not an OD Master, or you don't have working DNS. If this is the case, make sure your DNS is good and promote yourself to an OD Master. If you are already an OD Master, and you have already entered a number of users into the LDAP database you are right to not want to demote and then promote yourself to being a Master. Instead you can hand crank Kerberos from the command line.

First you need to set up some basic config files. Lucky for you there is a utility to help you with this

sudo kerberosautoconfig -r  -m  -u 

or in our example

sudo kerberosautoconfig -r AFP548.COM -m www.afp548.com -u

You will now have the configuration file /Library/Preferences/edu.mit.Kerberos, which we'll talk more about later.

Next you need to set up the kdc database with

sudo kdcsetup -f  -a  -p  -w 

Or in our example

sudo kdcsetup -f /LDAPv3/127.0.0.1/ -a mactroll -p notgoingtotellyou -w AFP548.COM

This gets the database rolling and creates a few initial principles for you. If the command balks at this, and you know you don't have anything important in your kdc files you can blow them away and start from scratch with

sudo rm -rf /var/db/krb5kdc/*

Then run the kdcsetup command again.

Now that you have your kdc configured you need to cross your fingers and start it

sudo krb5kdc

No news is good news here.

At this point the Open Directory section of Server Admin should indicate that the kdc is running. You now need to change the password of one of your users that is set to use an advanced password. Since your kdc wasn't running when you created any of your current users, none of them have principles in the kdc. Changing the user's password will change that. Additionally you can try to get your Password Server to create the Kerberos database for you. This isn't always going to work, depending on if the Password Server thought that you were kerberized to begin with, but it's fun to try.

sudo mkpassdb -kerberize

. Double-check to make sure the user now has a Kerberos authentication authority in their user record and test out your setup by using

kinit

or

kinit [e-mail]

if you need to actually specify the name.

This will prompt you for your password. If everything is groovy, you'll be returned to a prompt. If not you'll get an error and perhaps asked for your password again. If that's the case check out our troubleshooting article. Hopefully I'll have finished it by the time you really need it!

If sucsessful you can make sure by using

klist

Which should return a host principle for your kdc server.

Congratulations, you now have a working, albeit mostly useless, but working nonetheless kdc. Now continue on to the next section.

2. Keytabs

While the kdc keeps the password database, nothing else but the kdc can get into it. While this is good for security it kind of throws a wrench into getting a service fully kerberized. The AppleShare server, for example, needs to get access to the password, or key, that it shares with the kdc.

This is done through a keytab. Service keys are exported out of the kdc into a flat file that is only readable by root. This file, on both OS X and other Unix systems, defaults to /etc/krb5.keytab.

When the kdc is automagically set up for you, the keytab is also created. Isn't Apple nice? On a stock MIT Kerberos system you'd have to do this by hand.

You can see what's listed in your keytab by either using

ktutil

and reading the keytab in and then list it, or you can do this the easy way with

sudo klist -kt

This should spit back, on a healthy system, a collection of keys. On our sample afp548.com server you would see something like this

server:~ mactroll$ sudo klist -ktPassword:Keytab name: FILE:/etc/krb5.keytabKVNO Timestamp         Principal---- ----------------- --------------------------------------------------------   4 01/03/04 00:58:41 host/[e-mail]   4 01/03/04 00:58:41 host/[e-mail]   4 01/03/04 00:58:41 host/[e-mail]   3 01/03/04 00:58:41 smtp/[e-mail]   3 01/03/04 00:58:41 smtp/[e-mail]   3 01/03/04 00:58:41 smtp/[e-mail]   3 01/03/04 00:58:41 pop/[e-mail]   3 01/03/04 00:58:41 pop/[e-mail]   3 01/03/04 00:58:41 pop/[e-mail]   3 01/03/04 00:58:41 imap/[e-mail]   3 01/03/04 00:58:41 imap/[e-mail]   3 01/03/04 00:58:41 imap/[e-mail]   3 01/03/04 00:58:41 ftp/[e-mail]   3 01/03/04 00:58:41 ftp/[e-mail]   3 01/03/04 00:58:41 ftp/[e-mail]   3 01/03/04 00:58:41 afpserver/[e-mail]   3 01/03/04 00:58:41 afpserver/[e-mail]   3 01/03/04 00:58:41 afpserver/[e-mail]

It's normal to have three of each. Each one of these is encrypted in a different way, so your services can support more password types.

If you have a list of entries in your keytab, you should be g2g as the kids say to actually use Kerberos for some hot single sign on action.

Make sure that you have done a kinit and received your host principle. Then ssh to your server's DNS name. For example

ssh www.afp548.com

Through the magic of Kerberos you shouldn't have to enter in your password. In fact it might be tough to see that you even made a connection at all. Check the process list and the system log to make sure you actually ssh'd to the machine that you are currently on.

If this didn't work, and this is probably because you don't have a host principle in your keytab file, you can use this utility to populate your keytab.

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

Or in our example

sudo sso_util configure -r AFP548.COM -a mactroll -p mypass all

After this you should now have a full keytab, so try an ssh connection to yourself again.

3. Clients

An OS X client needs two pieces to be in place before it will seamlessly participate in a Kerberos system.

First it needs to have the aforementioned /Library/Preferences/edu.mit.Kerberos file. This is a non-sensitive plain text file that tells the client where it's kdc is. It can also hold additional Kerberos configuration options and application specific parameters. These extras usually aren't needed, however.

In a healthy Open Directory system the client automatically gets this file when it binds to the parent LDAP server. If you look at your LDAP database you will find a Kerberos configuration in the "config" directory at the root of the database. This is an XML-formatted version of the edu.mit.Kerberos file. When the client binds to the LDAP server using Directory Access or through DHCP, this file is converted into plaintext and installed on the client.

This config file should be stuffed into the LDAP database by the kerberosautoconfig command if you are doing this by hand.

In theory you should be able to make edits to this file on the LDAP server and the client machines will use the file with your changes when they bind. Also you should be able to create a file in the same place on a non-Apple LDAP server and fool any OS X clients into thinking they are dealing with a full-blown Open Directory server.

This bit is an Apple add-on to the standard MIT Kerberos setup, and a handy one at that.

The second piece that the client needs is to tell the loginwindow to begin the Kerberos process when you login. On 10.2 you had to edit /etc/authorization by hand to get the loginwindow to do this. Starting in though 10.3 it's already been done for you. However, if you want to further secure you connection you can edit /etc/authorization to force the server to validate itself to you before you trust it enough to use the TGT it gave you. More on this in a later part of this series.

4. Replication

With any network service if it is only provided by one machine you have a single point of failure. Kerberos has full support for replicating itself to a backup kdc.

On a traditional Unix system you would have to do a bit of work on your own to set this up. Host keys need to be exchanged and access control lists need to be set up so that the primary kdc will trust the secondary.

On OS X Server when you set up a second server, remember you need to have at least two unique server serial numbers to do this, you automatically get a replicant kdc on the replica server. That's cool and all Apple. Everything is taken care of for you.

On OS X Server the Password Server and the kdc have a rather symbiotic relationship. Since the Password Server already had a fully functional PKI encrypted replication solution, Apple leveraged that to replicate Kerberos. Whenever the kdc accepts a password change it pushes the change to the local Password Server running on the OS X Server. The Password server then replicates the change out, as it does with any Password Server initiated change. When the Password Server gets a password change, either directly from a user or from the Password Server replication process, it pushes the change to the local kdc. All nice and neat, and rather simple.

The end result of this is that a user can change their password on any Open Directory server, even if that server is offline from the rest of the network. When the server comes back online, the entire OD domain will synch and the most recent change will win.

5. Kerberos Utility

In case the command line just isn't graphical enough for you, there is a Kerberos application at /System/Library/CoreServices/Kerberos. This will allow you to get and destroy your tickets, plus see how long they have left to live. The icon in the dock showing you your TGT's lifetime is just flat out cool.

MIT wrote this application as part of their Kerberos for Macintosh package. Apple has put it into the default OS X install. It's handy for troubleshooting, certainly, but the average user should never have to use this.

Ed. Note: In 10.3 there was actually a fun little Easter Egg with this. Typing individually option-b-s-d would convert all of the button names into their CLI equivalents. Option-m-a-c would get you back to the normal ones. Sadly this was pulled from the 10.4 version.

6. Ticket cache

A standard MIT Kerberos setup will cache the TGT and other tickets the client receives in a cache file on the local machine's file system. Even though it is protected by file permissions there is still a possibility of someone compromising the system and getting to this file.

To help prevent that both Apple and Microsoft put this cache into RAM instead of on the local drive. That way there is no chance of the file hanging around after the machine reboots. It also makes it much harder for an attacker to get access to it.

7. End result

The Final result of all of this is that a user can log into an OS X client machine using a username and password from the Open Directory infrastructure and never have to enter a password again.

E-mail, filesharing and other network services can all be authenticated using Kerberos behind the scenes in a very secure fashion. The users won't understand how much science is going on deep inside the operating system to make this work, but that's ok.

Macintosh administrators across the world can now sleep soundly at night knowing their users are blissfully using a best of breed authentication solution.