Recipe 4.11 Getting Started with Kerberos

4.11.1 Problem

You want to set up an MIT Kerberos-5 Key Distribution Center (KDC).

4.11.2 Solution

4.11.3 Discussion

When choosing a realm name, normally you should use the DNS domain of your organization. Suppose ours is dogood.org. Here's an example of replacing EXAMPLE.COM with your realm and domain names in /etc/krb5.conf:

[libdefaults]
 default_realm = DOGOOD.ORG
[realms]
 DOGOOD.ORG = {
  kdc = kirby.dogood.org:88
  admin_server = kirby.dogood.org:749
  default_domain = dogood.org
 }
[domain_realm]
 .dogood.org = DOGOOD.ORG
 dogood.org = DOGOOD.ORG

The KDC principal database is the central repository of authentication information for the realm; it contains records for all principals (users and hosts) in the realm, including their authentication keys. These are strong random keys for hosts, or derived from passwords in the case of user principals.

# kdb5_util create
Initializing database '/var/kerberos/krb5kdc/principal' for realm 'DOGOOD.ORG',
master key name 'K/[email protected]'
You will be prompted for the database Master Password.
It is important that you NOT FORGET this password.
Enter KDC database master key: ********
Re-enter KDC database master key to verify: ********

Store the database master password in a safe place. The KDC needs it to start, and if you lose it, your realm database is useless and you will need to recreate it from scratch, including all user accounts.

kdb5_util stores the database in the files /var/kerberos/krb5kdc/principal* and stores the database master key in /var/kerberos/krb5kdc/.k5.DOGOOD.ORG. The key allows the KDC to start up unattended (e.g., on a reboot), but at the cost of some security, since it can now be stolen if the KDC host is compromised. You may remove this key file, but if so, you must enter the master password by hand on system startup and at various other points. For this recipe, we assume that you leave the key file in place, but we'll indicate where password entry would be necessary if you removed it.

When you start the KDC (adding the -m option to enter the master password if necessary):

Protect Your Key Distribution Server The KDC is the most sensitive part of the Kerberos system. The data in its database is equivalent to all your user's passwords; an attacker who steals it can impersonate any user or service in the system. For production use, KDCs should be locked down, particularly if your KDC master key is on disk to permit unattended restarts. Typically, a KDC should run only Kerberos services (TGT server, kadmin, Kerberos-5-to-4 credentials conversion) and have no other inbound network access. Administration, typically infrequent, should be done only at the console. At MIT, for example, KDCs are literally locked in a safe, with only a network and power cable emerging to the outside world. If you truly require remote administration, a possible compromise is login access via SSH, using only public-key authentication (and perhaps also Kerberos, but the likely time you'll need to get in is when Kerberos isn't working!).

# krb5kdc [-m]

monitor its operation by watching its log file in another window:

$ tail -f /var/log/krb5kdc.log
Mar 05 03:05:01 kirbyg krb5kdc[4231](info): setting up network...
Mar 05 03:05:01 kirby krb5kdc[4231](info): listening on fd 7: 192.168.10.5 port 88
Mar 05 03:05:01 kirby krb5kdc[4231](info): listening on fd 8: 192.168.10.5 port 750
Mar 05 03:05:01 kirby krb5kdc[4231](info): set up 2 sockets
Mar 05 03:05:01 kirby krb5kdc[4232](info): commencing operation

Next, in the realm database set up a Kerberos principal for yourself with administrative privileges, and a host principal for the KDC host. Kerberos includes a secure administration protocol for modifying the KDC database from any host over the network, using the kadmin utility. Of course, we can't use that yet as setup is not complete. To bootstrap, we modify the database directly using root privilege to write the database file, with a special version of kadmin called kadmin.local. Add the -m option to supply the master password if needed. Supposing that your username is pat and the KDC host is kirby.dogood.org:

# kadmin.local [-m]
Authenticating as principal root/[email protected] with password.
kadmin.local:  addpol users
kadmin.local:  addpol admin
kadmin.local:  addpol hosts
kadmin.local:  ank -policy users pat
Enter password for principal "[email protected]": ********
Re-enter password for principal "[email protected]": ********
Principal "[email protected]" created.

kadmin.local:  ank -policy admin pat/admin
Enter password for principal "pat/[email protected]": ********
Re-enter password for principal "pat/[email protected]": ********
Principal "pat/[email protected]" created.

kadmin.local:  ank -randkey -policy hosts host/kirby.dogood.org
Principal "host/[email protected]" created.
kadmin.local:  ktadd -k /etc/krb5.keytab host/kirby.dogood.org
Entry for principal host/kirby.dogood.org with kvno 3, encryption type 
  Triple DES cbc mode with HMAC/sha1 added to keytab WRFILE:/etc/krb5.keytab.

kadmin.local:  ktadd -k /var/kerberos/krb5kdc/kadm5.keytab \
                   kadmin/admin kadmin/changepw
Entry for principal kadmin/admin with kvno 3, encryption type
   Triple DES cbc mode with HMAC/sha1 added to keytab WRFILE:/var/kerberos/krb5kdc/
kadm5.keytab.
Entry for principal kadmin/changepw with kvno 3, encryption type
   Triple DES cbc mode with HMAC/sha1 added to keytab WRFILE:/var/kerberos/krb5kdc/
kadm5.keytab.

kadmin.local:  quit

The addpol command creates a policy—a collection of parameters and restrictions on accounts—which may be changed later. We create three policies for user, administrative, and host credentials, and begin applying them; this is a good idea even if not strictly needed, in case you want to start using policies later.

The ank command adds a new principal. The user and user administrative principals require passwords; for the host principal, we use the -randkey option, which generates a random key instead of using a password. When a user authenticates via Kerberos, she uses her password. A host also has credentials, but cannot supply a password, so a hosts's secret key is stored in a protected file, /etc/krb5.keytab.

Now, we can start up and test the kadmin service, which you can monitor via its log file, /var/log/kadmind.log:

# kadmind [-m]

First, try obtaining your Kerberos user credentials using kinit:

$ kinit
Password for [email protected]:

Having succeeded, use klist to examine your credentials:

$ klist
Ticket cache: FILE:/tmp/krb5cc_500
Default principal: [email protected]
Valid starting     Expires            Service principal
03/05/03 03:48:35  03/05/03 13:48:35  krbtgt/[email protected]

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

Now test the Kerberos administrative system, using the separate administrative password you assigned earlier:

$ kadmin
Authenticating as principal pat/[email protected] with password.
Enter password: ******** 
kadmin: listprincs 
 [list of all Kerberos principals in the database]
kadmin: quit 

Finally, test the local host principal by using Kerberos authentication with OpenSSH [Recipe 4.14] or Telnet [Recipe 4.15].

If you left the KDC master disk on disk at the beginning of this recipe, you may set the KDC and kadmin servers to start automatically on boot:

# chkconfig krb5kdc on
# chkconfig kadmin on

Otherwise, you will need to start them manually after every system reset, using the -m switch and typing in the KDC master database password.

4.11.4 See Also

kadmin(8), kadmind(8), kdb5_util(8), krb5kdc(8), kinit(1), klist(1), chkconfig(8) .