Debian GNU: Setting up MIT Kerberos 5

Kerberos is intended (and will be used) to centrally authenticate users on a network. User entries (called "principals"), consisting of principal names, secret keys, key aging information and Kerberos-specific data, are created using an administrative tool and saved in the Kerberos database.

When users type in their principal name and password anywhere on the network (within a Kerberos realm), their input is authenticated against the Kerberos database. In case of a successful authentication, the KDC ("Key Distribution Center") will issue users a "confirmation", called the TGT ("Ticket-Granting Ticket"). From that point on, and until their ticket expires, users will be transparently granted access to all network services they'll wish to use. (Here, the TGT will not grant access by itself — instead, it will be used in place of a password to automatically create further, service-specific tickets. Hence its name, the "Ticket-granting Ticket").

While the idea of a centralized network authentication is not unique, let's quickly identify Kerberos-specific elements in the authentication process:

You can find the complete Kerberos documentation at the MIT Kerberos website. Their on-line documentation is, however, only generated in multi-page HTML format — other more convenient formats (such as PostScript) are available within Kerberos release tarballs.

On all GNU/Linux-based platforms, Linux-PAM is available for service-specific authentication configuration. Linux-PAM is an implementation of PAM ("Pluggable Authentication Modules") from Sun Microsystems.

Network services, instead of having hard-coded authentication interfaces and decision methods, invoke PAM through a standard, pre-defined interface. It is then up to PAM to perform any and all authentication-related work, and report the result back to the application.

Exactly how PAM reaches the decision is none of the service's business. In traditional set-ups, that is most often done by asking and verifying usernames and passwords. In advanced networks, that could be retina scans or — Kerberos tickets.

PAM will allow for inclusion of Kerberos into the authentication path of all services, regardless of whether they natively support Kerberos or not.

You can find the proper introduction (and complete documentation) on the Linux-PAM website. Pay special attention to the PAM Configuration File Syntax page. Also take a look at the Linux-PAM(7) and pam(7) manual pages.

It's quite disappointing when you are not able to follow the instructions found in the documentation. Let's agree on a few points before going down to work:

sudo apt-get install krb5-{admin-server,kdc}

Debconf answers for reference:

Default Kerberos version 5 realm? SPINLOCK.HR
# (Your domain name in uppercase - a standard for naming Kerberos realms)

Does DNS contain pointers to your realm's Kerberos Servers? No
# (No DNS configuration is required for our setup)

Create the Kerberos KDC configuration automatically? Yes

Kerberos4 compatibility mode to use: none
# (No krb4 compatibility needed in our setup)

Run a Kerberos V5 to Kerberos V4 ticket conversion daemon? No

Should the data be purged as well as the package files? No

Run the Kerberos V5 administration daemon (kadmind)? Yes

What are the Kerberos servers for your realm? krb1.spinlock.hr
# (Make sure your DNS resolves krb1.spinlock.hr to
# the NETWORK IP of the server, NOT 127.0.0.1!). Hint is given in
# the section called “Conventions”.

What is the administrative server for your realm? krb1.spinlock.hr
# (Make sure your DNS resolves krb1.spinlock.hr to
# the NETWORK IP of the server, NOT 127.0.0.1!). Same hint as above.

As soon as the installation is done, the Kerberos admin server (kadmind) and the KDC will start. Kadmind will fail as, initially, there are no Kerberos realms created.

To create a Kerberos realm, invoke Debian-specific command krb5_newrealm. The command will ask for the master password. Pick one and write it down as it is rarely used, yet very important. Proceed to create the realm you "announced" earlier in the Debconf step (SPINLOCK.HR).

After the realm is created, we need to adjust the Kerberos config file, /etc/krb5.conf. The file needs to be the same on all Kerberos servers and clients on the network.

The file is split into sections; you should search for the section "[domain_realm]" and append your definition:

.spinlock.hr = SPINLOCK.HR
spinlock.hr = SPINLOCK.HR

At the bottom of the file, you should add the logging section:

[logging]
	kdc = FILE:/var/log/kerberos/krb5kdc.log
	admin_server = FILE:/var/log/kerberos/kadmin.log
	default = FILE:/var/log/kerberos/krb5lib.log

To apply the configuration, on the server run:

sudo mkdir /var/log/kerberos
sudo invoke-rc.d krb5-admin-server restart
sudo invoke-rc.d krb5-kdc restart

Don't forget to restart the log monitoring command you ran earlier (see the section called “Conventions”) — the tail program needs to pick up the new log files from the kerberos/ directory.

It's already the time to test the installation. We assume that both the admin server and the KDC can be restarted with no errors (which should be no problem to determine if you're monitoring the log files as advised).

To test the installation, we will run kadmin.local on the server.

Start kadmin.local, then type listprincs. That command should print out the list of principals (user, host and service accounts) in the database. The whole session should look like this:

sudo kadmin.local
Authenticating as principal root/admin@SPINLOCK.HR with password.

kadmin.local:  listprincs

K/M@SPINLOCK.HR
kadmin/admin@SPINLOCK.HR
kadmin/changepw@SPINLOCK.HR
kadmin/history@SPINLOCK.HR
krbtgt/SPINLOCK.HR@SPINLOCK.HR

kadmin.local:  quit

The kadmin command usually requires principal name and password before letting anyone access the administrative interface. However, kadmin.local is a variant of the command that must be run locally on the same machine as the KDC, and with administrator privileges. It is then able to open the Kerberos database file directly (taking advantage of Unix file permissions), without requiring extra privileges.

In the test step above, you might have noticed principal names similar to kadmin/admin@SPINLOCK.HR. The general naming syntax for principals is SPEC@REALM, where SPEC by convention consists of components separated by "/", and the default REALM can be omitted.

In the case of user names, the first component identifies the user name, and the second component, if present, identifies user role. For regular users, there will usually be one principal with no special role, named simply USERNAME. But when administrative or other roles are required, there will be no need to condense them all to one "root" prinicpal — each user can simply be given conveniently named additional principals with special privileges, such as USERNAME/admin.

In the case of service names, the components will be used to identify service and hostname, such as host/monarch.spinlock.hr or ldap/monarch.spinlock.hr.

Let's take a look at the /etc/krb5kdc/kadm5.acl file; it defines user access rights for the Kerberos database. For regular users with no special privileges, no action will be required. For admin users, we will want to grant all privileges, as hinted earlier in the section called “Principal Names”. To do this, make sure the following line is present in the file and enabled (that is, without the comment '#' character at the beginning):

*/admin *

While the above syntax might remind you of shell globbing, unfortunately it does not work that way at all. The only matching character is the asterisk, and it can only be used in form of "component1/*" or "*/component2".

Make sure to restart the admin server:

sudo invoke-rc.d krb5-admin-server restart

Kerberos "policies" offer an elegant way to sort principals into a kind of categories and to automatically apply corresponding defaults onto newly created principals.

Without going further into the discussion, let's create four basic policies: for admins, hosts, services and users. In this example, each policy will define a minimum password strength for the corresponding group.

sudo kadmin.local
Authenticating as principal root/admin@SPINLOCK.HR with password.

kadmin.local:  add_policy -minlength 8 -minclasses 3 admin
kadmin.local:  add_policy -minlength 8 -minclasses 4 host
kadmin.local:  add_policy -minlength 8 -minclasses 4 service
kadmin.local:  add_policy -minlength 8 -minclasses 2 user

kadmin.local:  quit

As you might have noticed, the kadmin.local command identified us as the principal root/admin. Still, that principal does not actually exist in the database so we might as well create it now. Once the principal is actually there, wel wil be able to connect to the administrative server using kadmin from any machine within the Kerberos realm, and not just by using kadmin.local on the Kerberos server.

While creating a principal based on your regular identity (such as USERNAME/admin) is preferred, we'll create a principal named root/admin here to focus on the relevant:

sudo kadmin.local
Authenticating as principal root/admin@SPINLOCK.HR with password.

kadmin.local:  addprinc -policy admin root/admin

Enter password for principal "root/admin@SPINLOCK.HR": PASSWORD
Re-enter password for principal "root/admin@SPINLOCK.HR": PASSWORD
Principal "root/admin@SPINLOCK.HR" created.

kadmin.local:  quit

Now that the root/admin principal exists in the Kerberos database, we should be able to use kadmin just as we used kadmin.local. The only exception, of course, is that kadmin will prompt for a password to connect to the Kerberos admin server.

Double-check that all the permissions are granted to admin roles in the /etc/krb5kdc/kadm5.acl (as explained in the section called “Access rights”), and that the admin server has been restarted to read the new configuration; then proceed to test kadmin connection from either the server or the client:

sudo kadmin -p root/admin
Authenticating as principal root/admin@SPINLOCK.HR with password.

Password for root/admin@SPINLOCK.HR: PASSWORD

kadmin:  listprincs

K/M@SPINLOCK.HR
kadmin/admin@SPINLOCK.HR
kadmin/changepw@SPINLOCK.HR
kadmin/history@SPINLOCK.HR
krbtgt/SPINLOCK.HR@SPINLOCK.HR
root/admin@SPINLOCK.HR

kadmin:  quit

Let's add a principal that will correspond to your regular, unprivileged user account. In our example, the username will be called "mirko". We've essentially performed this procedure for the root/admin principal above, but we'll repeat it here using a different policy, replacing mirko with your actual username, and replacing PASSWORD with an actual password:

sudo kadmin -p root/admin
Authenticating as principal root/admin@SPINLOCK.HR with password.

Password for root/admin@SPINLOCK.HR: PASSWORD

kadmin:  addprinc -policy user mirko

Enter password for principal "mirko@SPINLOCK.HR": PASSWORD
Re-enter password for principal "mirko@SPINLOCK.HR": PASSWORD
Principal "mirko@SPINLOCK.HR" created.

kadmin:  quit

As hinted in the introduction, each user is expected to type in the password once, to obtain the initial TGT (Ticket-granting Ticket). Obtained tickets are saved to a so-called ticket cache, which is most commonly a file named /tmp/krb5cc_*, stored on the user's workstation.

Let's run the klist command to inspect our ticket cache. As one might guess, since we did not obtain any tickets yet, the cache will be empty:

klist -5

klist: No credentials cache found (ticket cache FILE:/tmp/krb5cc_1000)

Let's use kinit again, this time to obtain the ticket and then re-inspect the ticket cache. If the command seemingly "hangs" and does nothing, wait a few seconds — DNS misconfiguration may cause a delay.

kinit

Password for mirko@SPINLOCK.HR: PASSWORD

klist -5

Ticket cache: FILE:/tmp/krb5cc_1000
Default principal: mirko@SPINLOCK.HR

Valid starting     Expires            Service principal
11/22/06 22:30:36  11/23/06 08:30:33  krbtgt/SPINLOCK.HR@SPINLOCK.HR

If you remember the story from the beginning, you will recognize the "krbtgt" to be the Ticket-granting Ticket.

All great. Let's run kdestroy to terminate the ticket now.

To actually use Kerberos, we need to install kerberized versions of the standard services.

Each service may support Kerberos authentication either by having native Kerberos support, or by delegating the authentication work to the PAM subsystem.

In your Debian GNU repository, there will be packages like krb-ftpd, krb5-telnetd and krb5-rsh-server. Those are replacement services for ftp, telnet and rsh with direct Kerberos (and encryption) support.

Let's install the krb5-rsh-server. Ensure that the service runs after installation; it is started from inetd, so inetd must be running and the kshell and eklogin services need to be enabled in /etc/inetd.conf.

sudo apt-get install openbsd-inetd
sudo apt-get install krb5-rsh-server

sudo update-rc.d -f openbsd-inetd remove
sudo update-rc.d openbsd-inetd defaults
sudo invoke-rc.d openbsd-inetd restart

To connect to a kerberized service on a certain server, the service itself must have a corresponding principal in the Kerberos database. This is because the Kerberos server acts as a trusted 3rd party and performs mutual authentication as explained in the section called “The role of Kerberos within a network”. The generic service name for telnet, rsh, ssh and related protocols is "host", so let's create the necessary principal with a randomly-generated password. Make sure that you also export the key to a keytab file as shown and within the same invocation of kadmin, to save yourself from getting an error about the "Key version number" being incorrect:

sudo kadmin -p root/admin
Authenticating as principal root/admin@SPINLOCK.HR with password.

Password for root/admin@SPINLOCK.HR: PASSWORD

kadmin:  addprinc -policy service -randkey host/monarch.spinlock.hr

Principal "host/monarch.spinlock.hr@SPINLOCK.HR" created.

kadmin:  ktadd -k /etc/krb5.keytab  host/monarch.spinlock.hr
Entry for principal host/monarch.spinlock.hr@SPINLOCK.HR with kvno 3, encryption type Triple DES cbc mode with HMAC/sha1 added to keytab WRFILE:/etc/krb5.keytab.
Entry for principal host/monarch.spinlock.hr@SPINLOCK.HR with kvno 3, encryption type DES cbc mode with CRC-32 added to keytab WRFILE:/etc/krb5.keytab.

kadmin:  quit

Ensure that this keytab file, /etc/krb5.keytab, is moved to the rsh server machine. If the rsh server and the Kerberos server are the same machine, no copying to the remote location is necessary.

Let's install kerberized versions of the basic client programs:

sudo apt-get install krb5-clients

One of the client programs, krb5-rsh, will allow you connect to the secure rsh server, automatically and without asking for any user names or passwords. The connection will also be encrypted as long as the -x switch is used.

As we have taken care of all the pre-requisites, we can try connecting:

Obtain Kerberos ticket:

kinit

Password for USERNAME@SPINLOCK.HR: PASSWORD

Connect:

krb5-rsh -x -PN krb1.spinlock.hr

This rlogin session is encrypting all data transmissions.
Last login: Mon Nov 27 16:49:49 from monarch
Linux monarch 2.4.27-2-686 #1 Mon May 16 17:03:22 JST 2005 i686 GNU/Linux

The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.

Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
You have new mail.

logout
Connection closed.

Congratulations! You have a working Kerberos setup.

If anything is not working, consult the section called “Troubleshooting Kerberos connection” — it contains an extensive list of possible errors and the corresponding solutions!

krb5-rsh -x -PN krb1.spinlock.hr


Trying krb4 rlogin...
krb_sendauth failed: You have no tickets cached

You have no valid Kerberos tickets, which can be verified by running klist -5 (the output will either be empty or show expired tickets). Obtain a new ticket using kinit:

kinit PRINCIPAL_NAME

krb5-rsh -PN krb1.spinlock.hr


connect to address 192.168.7.12: Connection refused
Trying krb4 rlogin...
connect to address 192.168.7.12: Connection refused
trying normal rlogin (/usr/bin/netkit-rlogin)
exec: No such file or directory

Let's take a look at this. First of all, you can see that krb5-rsh has some fallbacks built-in. It first tries to connect using the Kerberos 5 protocol, then Kerberos 4, and then using the normal, non-kerberized rsh. We are only interested in the krb5 result. If any of the other two methods succeed (the krb4 or plain rsh), it's still not what we want (and you will probably want to disable them somehow, because no one setting up a new Kerberos realm in the 21st century should be running either krb4 or unprotected rsh).

So where's the problem? Assuming that you did everything right (installed krb5-rsh-server and restarted inetd), the problem is very simple. Namely, by default, kerberized servers in Debian do not accept unencrypted connections! So, on next attempt, add -x on the command line.

krb5-rsh -PN -x krb1.spinlock.hr

krb5-rsh -PN -x krb1.spinlock.hr


error getting credentials: Server not found in Kerberos database

As explained in the section called “The role of Kerberos within a network”, both the users and the services must have an appropriate principal entry in the Kerberos database. While users are in form of NAME/ROLE, services are in form SERVICE-NAME/HOSTNAME. So we need to add a principal for service "host" (common name for all shell services), on host where the service is provided — monarch.spinlock.hr. (Strictly, the service is provided on the server, on krb1.spinlock.hr, but in a single-machine setup, the hostname's FQDN returns monarch.spinlock.hr so we must use that).

Within the same session, you will almost always want to export that principal's key to a keytab file. Exporting will not work as intended if the key was not created in a single kadmin session, so the below solution deletes the existing key (if any), creates it anew and exports it to a file. As to what you need to do with the keytab file after creation — you need to move it from the Kerberos server onto the machine providing the service. If that is the same machine, no moving is necessary.

As most of the errors really boil down to this step, we also take care of re-initializing the ticket properly, to minimize the chance of a mistake:

rm /etc/krb5.keytab

kdestroy

sudo kadmin.local
Authenticating as principal root/admin@SPINLOCK.HR with password.

kadmin.local:  delprinc host/monarch.spinlock.hr
Are you sure you want to delete the principal "host/monarch.spinlock.hr@SPINLOCK.HR"? (yes/no): yes
Principal "host/monarch.spinlock.hr@SPINLOCK.HR" deleted.
Make sure that you have removed this principal from all ACLs before reusing.

kadmin.local:  addprinc -randkey host/monarch.spinlock.hr

WARNING: no policy specified for host/monarch.spinlock.hr@SPINLOCK.HR; defaulting to no policy
Principal "host/monarch.spinlock.hr@SPINLOCK.HR" created.

kadmin.local:  ktadd -k /etc/krb5.keytab host/monarch.spinlock.hr

kadmin.local: quit

kinit root/admin

krb5-rsh -PN -x krb1.spinlock.hr


Couldn't authenticate to server: Server rejected authentication (during sendauth exchange)
Server returned error code 60 (Generic error (see e-text))
Error text sent from server: No such file or directory

The above error indicates that we should pay attention to the "e-text" (error text returned to the client). The error text tells us, in kind of a confusing way (since — you see — there is no filename reported), that the /etc/krb5.keytab file on the rsh server is missing altogether. This file needs to exist and contain the service key. The way to obtain the file and the key is to follow the recipe from the section called “Error: Server not found in Kerberos database”.

krb5-rsh -PN -x krb1.spinlock.hr


Couldn't authenticate to server: Server rejected authentication (during sendauth exchange)
Server returned error code 60 (Generic error (see e-text))
Error text sent from server: Key table entry not found

The server did accept the connection, but the e-text "Key table entry not found" indicates that the service principal (created earlier, host/monarch.spinlock.hr) is not listed in the keytab file on rsh server. Follow the recipe in the section called “Error: Server not found in Kerberos database”.

krb5-rsh -PN -x krb1.spinlock.hr


Couldn't authenticate to server: Server rejected authentication (during sendauth exchange)
Server returned error code 60 (Generic error (see e-text))
Error text sent from server: Key version number for principal in key table is incorrect

The service key has changed on the Kerberos server, and the service did not succeed in proving its identity to the Kerberos server — the file /etc/krb5.keytab on the service did not contain the correct key. Have in mind that the key changes if you run ktadd from within the kadmin shell (read up on ktadd behavior in kadmin(8)). Follow the recipe in the section called “Error: Server not found in Kerberos database”.

kinit root/admin


kinit(v5): Client not found in Kerberos database while getting initial credentials

This is Kerberos way of saying "User not found". You either misspelled the principal name ("root/admin" in this case), or you didn't add the principal to the kerberos database in the first place. Adding a principal is performed using the addprinc command as shown in the section called “Creating first privileged principal” or the section called “Creating first unprivileged principal”.

sudo kadmin -p root/admin


kadmin: Client not found in Kerberos database while initializing kadmin interface

This is Kerberos way of saying "User not found". You either misspelled the principal name ("root/admin" in this case), or you didn't add the principal to the kerberos database in the first place. Adding a principal is performed using the addprinc command as shown in the section called “Creating first privileged principal” or the section called “Creating first unprivileged principal”.

krb5-rsh -PN -x krb1.spinlock.hr


Couldn't authenticate to server: Server rejected authentication (during sendauth exchange)
Server returned error code 31 (Decrypt integrity check failed)
Error text sent from server: Decrypt integrity check failed

This is Kerberos way of saying "Password incorrect". In this case, it means that the service key changed on the server, and your your ticket cache no longer contains the ticket with the correct key. Running kdestroy; kinit should obtain a new ticket and solve the problem.

account sufficient        pam_unix.so
account sufficient        pam_krb5.so
account required          pam_deny.so

auth    sufficient        pam_unix.so nullok_secure
auth    sufficient        pam_krb5.so use_first_pass
auth    required          pam_deny.so

password  sufficient   pam_unix.so nullok obscure md5
password  sufficient   pam_krb5.so use_first_pass
password  required     pam_deny.so

session required pam_limits.so
session optional pam_krb5.so
session optional pam_unix.so