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

1. Confirm that Kerberos is installed; if not, install the necessary Red Hat packages:

   $ rpm -q krb5-server krb5-workstation

2. Add /usr/kerberos/bin and /usr/kerberos/sbin to your search path.

3. Choose a realm name (normally your DNS domain), and in the following files:

   /etc/krb5.conf

   /var/kerberos/krb5kdc/kdc.conf

   /var/kerberos/krb5kdc/kadm5.acl

   replace all occurrences of EXAMPLE.COM with your realm and domain.

4. Create the KDC principal database, and choose a master password:

   # kdb5_util create

5. Start the KDC:

   # krb5kdc [-m]

6. Set up a Kerberos principal for yourself with administrative privileges, and a host principal for the KDC host. (Note the prompt is "kadmin.local:".) Suppose your KDC host is kirby.dogood.org:

   # kadmin.local [-m] kadmin.local: addpol users  kadmin.local: addpol admin  kadmin.local: addpol hosts  kadmin.local: ank -policy users  username  kadmin.local: ank -policy admin  username /admin  kadmin.local: ank -randkey -policy hosts host/kirby.dogood.org  kadmin.local: ktadd -k /var/kerberos/krb5kdc/kadm5.keytab \               kadmin/admin kadmin/changepw  kadmin.local: quit 

7. Start up the kadmin service:

   # kadmind [-m]

8. Test by obtaining your own Kerberos user credentials, and listing them:

   $ kinit $ klist

9. Test the Kerberos administrative system (note the prompt is "kadmin:"):

   $ kadmin kadmin: listprincs kadmin: quit

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/[e-mail]' 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/[e-mail] with password. kadmin.local:  addpol users kadmin.local:  addpol admin kadmin.local:  addpol hosts kadmin.local:  ank -policy users pat Enter password for principal "[e-mail]": ******** Re-enter password for principal "[e-mail]": ******** Principal "[e-mail]" created. kadmin.local:  ank -policy admin pat/admin Enter password for principal "pat/[e-mail]": ******** Re-enter password for principal "pat/[e-mail]": ******** Principal "pat/[e-mail]" created. kadmin.local:  ank -randkey -policy hosts host/kirby.dogood.org Principal "host/[e-mail]" 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 [e-mail]:

Having succeeded, use klist to examine your credentials:

$ klist Ticket cache: FILE:/tmp/krb5cc_500 Default principal: [e-mail] Valid starting     Expires            Service principal 03/05/03 03:48:35  03/05/03 13:48:35  krbtgt/[e-mail] 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/[e-mail] 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) .