MIT Kerberos V master on Debian squeeze

First developed at the Massachusetts Institute of Technology (MIT) in the early 1980s, Kerberos is a network protocol that offers highly secure, cross-platform, universal authentication for users, hosts and services. In addition, it is the most common single sign-on technology used in Unix-like environments. Kerberos makes use of secret-key cryptography and a centralized Key Distribution Center (KDC) server containing a database of principals; pairs of names and passwords. The system also relies heavily on timestamps, so reasonably accurate time synchronization among all participating hosts is essential.

Once authenticated, users receive a Ticket Granting Ticket (TGT) from the KDC that is thereafter used to automatically request other temporary tickets with which to gain access to hosts and services that are part of the same realm: a set of objects under the administrative control of a distinct Kerberos installation. Indeed, hosts and services must also have entries in the KDC, as well as in their local keytab file (a table of encryption keys), before users can access them. Kerberized services − those that support Kerberos natively − are to be preferred in such environments, as only these can silently verify a user's existing Kerberos credentials. Most other services are capable of working with Kerberos through PAM, but if they are accessible only via the network, they will unfortunately prompt the user for their password.

In this example, MIT Kerberos V is installed on a host running Debian 6.0 (squeeze). If followed properly, this step-by-step process should produce a new realm with a master KDC and Kerberos administration server. But, before the actual Kerberos installation process can begin, it will first be necessary to install Debian on a new host called kdc1.example.com. A DNS server must also be available on the network with a zone file to which forward and reverse mappings can be added for this host, as well as an alias for it called krb.example.com. After the initial installation of the operating system, make sure these packages are installed on the system as well:

~# apt-get install ssh ntp ntpdate xinetd nmap

Consequently, edit /etc/ntp.conf so that the machine synchronizes to a common NTP server (preferably a local one) and edit /etc/default/ntpdate to use the same host also. Now the installation process for the MIT Kerberos V master KDC can begin:

On the new host, kdc1.example.com, start by installing these two packages:

~# apt-get install krb5-{admin-server,user}

A total of four packages are installed as a result, including two dependencies:

krb5-admin-server          1.8.3+dfsg-1                MIT Kerberos master server (kadmind)
krb5-config                2.2                         Configuration files for Kerberos Version 5
krb5-kdc                   1.8.3+dfsg-1                MIT Kerberos key server (KDC)
krb5-user                  1.8.3+dfsg-1                Basic programs to authenticate using MIT Kerberos

During this install process, a few questions are asked regarding Kerberos authentication that should be answered as follows:

Default Kerberos version 5 realm: EXAMPLE.COM
Kerberos servers for your realm: kdc1.example.com
Administrative server for your Kerberos realm: krb.example.com

At the end of this install process, two problems appear:

Note: xinetd currently is not fully supported by update-inetd.
      Please consult /usr/share/doc/xinetd/README.Debian and itox(8).
krb5kdc: cannot initialize realm EXAMPLE.COM - see log file for details
Setting up krb5-admin-server (1.8.3+dfsg-1) ...
kadmind: No such file or directory while initializing, aborting
~# _

The first problem is unfortunate, but xinetd is preferred here because of its IPv6 compatibility. In contrast, openbsd-inetd does not support IPv6, which limits its use in a modern networking environment. The super-server is used to run the Kerberos KDC database propagation daemon; it is really only necessary to run it on slave KDCs, but it is good to install it anyway in case the role of this host ever needs to be changed. To get it running with xinetd, create a file called /etc/xinetd.d/krb_prop with the following contents:

service krb_prop
{
	disable		= no
	socket_type	= stream
	protocol	= tcp
	user		= root
	wait		= no
	server		= /usr/sbin/kpropd
}

After saving this file, restart xinetd:

~# /etc/init.d/xinetd restart

The second problem is that kadmind, the administration daemon, failed to start. This is because the realm, EXAMPLE.COM, or rather the database file for it (/var/lib/krb5kdc/principal), has not yet been created.

To create the new realm, use the krb5_newrealm command. Be careful, because it should be used only once.

~# krb5_newrealm
This script should be run on the master KDC/admin server to initialize
a Kerberos realm.  It will ask you to type in a master key password.
This password will be used to generate a key that is stored in
/etc/krb5kdc/stash.  You should try to remember this password, but it
is much more important that it be a strong password than that it be
remembered.  However, if you lose the password and /etc/krb5kdc/stash,
you cannot decrypt your Kerberos database.
Loading random data

At this point the script may pause; sometimes for only a moment, other times for considerably longer. Patience is a virtue.

Initializing database '/var/lib/krb5kdc/principal' for realm
'EXAMPLE.COM', master key name 'K/M@EXAMPLE.COM'
You will be prompted for the database Master Password.
It is important that you NOT FORGET this password.
Enter KDC database master key: adamanteus
Re-enter KDC database master key to verify: adamanteus

Now that your realm is set up you may wish to create an administrative
principal using the addprinc subcommand of the kadmin.local program.
Then, this principal can be added to /etc/krb5kdc/kadm5.acl so that
you can use the kadmin program on other computers.  Kerberos admin
principals usually belong to a single user and end in /admin.  For
example, if jruser is a Kerberos administrator, then in addition to
the normal jruser principal, a jruser/admin principal should be
created.

Don't forget to set up DNS information so your clients can find your
KDC and admin servers.  Doing so is documented in the administration
guide.
~# _

The only request that is made is for a password. In this case, adamanteus was used. Whatever password is used, this one is very important, so do not forget it!

Edit /etc/krb5kdc/kadm5.acl and enable/add the following two lines:

*/admin *
admin *

This is to allow certain principals, admin and names ending in /admin, to perform any operation.

Replace the Kerberos realm configuration file, /etc/krb5.conf. This file is initially created by the Debian installer and contains information about the realms of a number of famous institutions, but none of that is necessary in this case. Instead, add this to the new file:

[libdefaults]
        default_realm = EXAMPLE.COM
        forwardable = true
        proxiable = true

[realms]
	EXAMPLE.COM = {
		kdc = kdc1.example.com
		admin_server = krb.example.com
	}

[domain_realm]
	.example.com = EXAMPLE.COM
	example.com = EXAMPLE.COM

[logging]
	kdc = FILE:/var/log/krb5/kdc.log
	admin_server = FILE:/var/log/krb5/kadmin.log
	default = FILE:/var/log/krb5/kadmin.log

This file is divided into a number of sections. The first, [libdefaults], contains default values used by the Kerberos V library. It has many possible settings, but the only ones used here are default_realm, which is used by the client, and forwardable and proxiable, which apply to initial tickets.

The [realms] section contains subsections that start with the name of a Kerberos realm. In turn, each subsection contains information specific to that realm, such as (possibly multiple) kdc and (a single) admin_server entries to locate important hosts.

The [domain_realm] section is for mapping DNS domain names to Kerberos realms. It may seem unnecessary in cases such as this when they are the same (DNS entries are not case sensitive), but of course this is not always so. Each tag is written in lower case and can be a hostname or a domain name, the latter being prefixed with a dot. If no mappings apply, the realm is obtained by converting the domain portion of a hostname to upper case.

The last section, [logging], is optional, but recommended. It determines how a particular host should perform its logging. The settings used here specify that Kerberos log output from the KDC server should be sent to one log file and output from the administrative server to another. A default log file has also been defined, but in practice it may never be used, so in this case its output is also sent to the log file for the administrative server.

After /etc/krb5.conf has been saved, create the Kerberos log directory:

~# mkdir /var/log/krb5

To prevent the log files from growing too large, create a pair of logrotate configuration files. First, edit /etc/logrotate.d/krb5-kdc and give it the following contents:

/var/log/krb5/kdc.log {
	daily
	missingok
	rotate 7
	compress
	delaycompress
	notifempty
	postrotate
		/etc/init.d/krb5-kdc restart > /dev/null
	endscript
}

Then edit /etc/logrotate.d/krb5-kadmin and give it this slightly different configuration:

/var/log/krb5/kadmin.log {
	daily
	missingok
	rotate 7
	compress
	delaycompress
	notifempty
	postrotate
		/etc/init.d/krb5-admin-server restart > /dev/null
	endscript
}

Start up the administrative interface for the Kerberos database and use it to allow more flexible lifetime and renewal time frames for the ticket granting ticket (TGT) service. The commands and their responses should look like this:

~# kadmin.local
Authenticating as principal root/admin@EXAMPLE.COM with password.
kadmin.local:  modprinc -maxlife "1 day" -maxrenewlife "90 day" \
               krbtgt/EXAMPLE.COM@EXAMPLE.COM
Principal "krbtgt/EXAMPLE.COM@EXAMPLE.COM" modified.
kadmin.local:  q
~# _

The values entered above are instead of 10 hours and 1 day respectively, which are the default values. However, every organization should use values that best suit their own security needs. As for kadmin.local, this is a fail-safe version of the kadmin tool that can only be used on the KDC as root and requires no password to modify the database directly. The kadmin tool, on the other hand, can be used from anywhere on the network.

Now edit /etc/krb5kdc/kdc.conf and modify these two lines to reflect the changes made above:

max_life = 1d 0h 0m 0s
max_renewable_life = 90d 0h 0m 0s

Restart the Kerberos admin and KDC servers:

~# /etc/init.d/krb5-admin-server restart ; /etc/init.d/krb5-kdc restart

Restarting these servers is only necessary after any associated configuration files have been changed.

Start up kadmin.local once more to create the admin principal:

~# kadmin.local
Authenticating as principal root/admin@EXAMPLE.COM with password.
kadmin.local:  addprinc admin
WARNING: no policy specified for admin@EXAMPLE.COM; defaulting to 
no policy
Enter password for principal "admin@EXAMPLE.COM": Lampropeltis
Re-enter password for principal "admin@EXAMPLE.COM": Lampropeltis
Principal "admin@EXAMPLE.COM" created.
kadmin.local:  q
~# _

To be sure, the password given here is Lampropeltis.

If a line exists in /etc/hosts that maps a loopback address to the FQDN, which in this case is kdc1.example.com, it can prevent kadmin from starting up. If this line exists, remove it.

Use kadmin to create a host principal and a keytab file for the new master KDC by issuing the following commands:

~# kadmin -p admin
Authenticating as principal admin with password.
Password for admin@EXAMPLE.COM: Lampropeltis
kadmin:  addprinc -randkey host/kdc1.example.com
WARNING: no policy specified for host/kdc1.example.com@EXAMPLE.COM; 
defaulting to no policy
Principal "host/kdc1.example.com@EXAMPLE.COM" created.
kadmin:  ktadd host/kdc1.example.com
Entry for principal host/kdc1.example.com with kvno 2, encryption type 
AES-256 CTS mode with 96-bit SHA-1 HMAC added to keytab 
WRFILE:/etc/krb5.keytab.
Entry for principal host/kdc1.example.com with kvno 2, encryption type 
ArcFour with HMAC/md5 added to keytab 
WRFILE:/etc/krb5.keytab.
Entry for principal host/kdc1.example.com with kvno 2, encryption type 
Triple DES cbc mode with HMAC/sha1 added to keytab 
WRFILE:/etc/krb5.keytab.
Entry for principal host/kdc1.example.com with kvno 2, encryption type 
DES cbc mode with CRC-32 added to keytab 
WRFILE:/etc/krb5.keytab.
kadmin:  q
~# _

The -randkey switch is used because a machine cannot enter a password. By default, Kerberos saves its keys in /etc/krb5.keytab. To list the keys in this file, use the klist -ke command. Such keytab files should be created for and saved on all of the various client machines that are part of a Kerberos realm.

Using some standard tools, there are a number of ways to test that the new KDC is working. Start by requesting a valid ticket for the new principal, admin:

~# kinit admin
Password for admin@EXAMPLE.COM: Lampropeltis
~# _

Once given the right password (Lampropeltis), a list of the tickets obtained can be viewed:

~# klist
Ticket cache: FILE:/tmp/krb5cc_0
Default principal: admin@EXAMPLE.COM

Valid starting     Expires            Service principal
10/09/10 19:57:52  10/10/10 19:57:47  krbtgt/EXAMPLE.COM@EXAMPLE.COM
~# _

Only one ticket is listed here, the TGT, and it has a validity period of one day. Tickets can also be deleted:

~# kdestroy
~# klist
klist: No credentials cache found (ticket cache FILE:/tmp/krb5cc_0)
~# _

The administration interface can be used to list all of the principals in the KDC:

~# kadmin -p admin
Authenticating as principal admin with password.
Password for admin@EXAMPLE.COM: Lampropeltis
kadmin:  listprincs
K/M@EXAMPLE.COM
admin@EXAMPLE.COM
host/kdc1.example.com@EXAMPLE.COM
kadmin/admin@EXAMPLE.COM
kadmin/changepw@EXAMPLE.COM
kadmin/history@EXAMPLE.COM
kadmin/kdc1.example.com@EXAMPLE.COM
krbtgt/EXAMPLE.COM@EXAMPLE.COM
kadmin:  _

Two principals of interest here include K/M, the Kerberos Master Key principal (password adamanteus), and krbtgt, which is for the TGT service. All information about a principal can be retrieved with the getprinc command. For example:

kadmin:  getprinc krbtgt/EXAMPLE.COM@EXAMPLE.COM
Principal: krbtgt/EXAMPLE.COM@EXAMPLE.COM
Expiration date: [never]
Last password change: [never]
Password expiration date: [none]
Maximum ticket life: 1 day 00:00:00
Maximum renewable life: 90 days 00:00:00
Last modified: Sat Oct 09 19:55:59 CEST 2010 (root/admin@EXAMPLE.COM)
Last successful authentication: [never]
Last failed authentication: [never]
Failed password attempts: 0
Number of keys: 5
Key: vno 1, AES-256 CTS mode with 96-bit SHA-1 HMAC, no salt
Key: vno 1, ArcFour with HMAC/md5, no salt
Key: vno 1, Triple DES cbc mode with HMAC/sha1, no salt
Key: vno 1, DES cbc mode with CRC-32, no salt
Key: vno 1, DES cbc mode with RSA-MD5, no salt
MKey: vno 1
Attributes: REQUIRES_PRE_AUTH
Policy: [none]
kadmin:  q
~# _

Finally, run the following command to list all of the open TCP and UDP ports used by Kerberos:

~# nmap -sU -sT -p U:88,464,750,T:464,749,754 localhost

Starting Nmap 5.00 ( http://nmap.org ) at 2010-10-09 21:48 CEST
Warning: Hostname localhost resolves to 2 IPs. Using 127.0.0.1.
Interesting ports on localhost (127.0.0.1):
PORT    STATE         SERVICE
464/tcp open          kpasswd5
749/tcp open          kerberos-adm
754/tcp open          krb_prop
88/udp  open|filtered kerberos-sec
464/udp open|filtered kpasswd5
750/udp open|filtered kerberos

Nmap done: 1 IP address (1 host up) scanned in 3.10 seconds
~# _

The services are:

NB: Currently, kadmind does not support IPv6. Hopefully this will be fixed in MIT Kerberos version 1.9.

• MIT Kerberos V slave on Debian squeeze
• MIT Kerberos V client on Debian squeeze
• MIT Kerberos V master on Debian lenny

• Eastlake D, Panitz A. 1999. RFC2606 − Reserved Top Level DNS Names. The Internet Society. HTML at the Internet FAQ Archives.
• Kohl J, Neuman C. 1993. RFC1510 − The Kerberos Network Authentication Service (V5). HTML at the Internet FAQ Archives.

• Garman J. 2003. Kerberos, The Definitive Guide. O'Reilly & Associates, Inc. ISBN-13 978-0-596-00403-3. 253 pp. See pages 48-62.
• Massachusetts Institute of Technology. 1985-2010. Kerberos V5 System Administrator's Guide. HTML at the Massachusetts Institute of Technology (MIT).
• Milicchio F, Gehrke WA. 2007. Distributed Services with OpenAFS. Springer-Verlag. ISBN-13 978-3-540-36633-1. 395 pp. See pages 36-45.
• Ocelic D. 2006-2010. Debian GNU: Setting up MIT Kerberos 5. HTML at Spinlock Solutions.