Exercise 3: Build a KDC
=======================

These exercises assume your host is pc1.ws.nsrc.org and you will be
building a realm REALM1.WS.NSRC.ORG - change `1` to the appropriate
value for your machine.

1. Install ntp
--------------

Because tickets are timestamped, it's important that your machine always
has an accurately synchronized clock. Double-check it's installed:

    # apt-get install ntp

This will run a daemon (ntpd) which keeps your clock synchronized.

Note: if you have a large network then it makes sense to have two local
timeservers and all other machines sync to those. You would then change
/etc/ntpd.conf to point to your time server(s).

2. Install kdc packages
-----------------------

    # apt-get install krb5-kdc krb5-admin-server

If you get a dialog box about setting up a kerberos realm, just accept [Ok]

3. Configure krb5 library
-------------------------

Now we are going to configure the krb5 client library, manually associating
your own machine with your own realm. (We could instead change the DNS,
but doing it here lets you control your own settings)

    # editor /etc/krb5.conf
    [libdefaults]
    default_realm = REALM1.WS.NSRC.ORG
    dns_lookup_realm = true
    dns_lookup_kdc = true

    [realms]
    REALM1.WS.NSRC.ORG = {
            kdc = pc1.ws.nsrc.org
            admin_server = pc1.ws.nsrc.org
    }

    [domain_realm]
    pc1.ws.nsrc.org = REALM1.WS.NSRC.ORG

4. Create and initialize your database
--------------------------------------

Create Kerberos database:

    kdb5_util create -r REALM1.WS.NSRC.ORG -s
    # This can pause for several minutes. Eventually you will be asked to
    # choose a database master password. Use "abcd" for this exercise,
    # but normally you'd choose something much stronger.

Create the ACL file and grant admin rights to all */admin principals:

    # editor /etc/krb5kdc/kadm5.acl
    */admin@REALM1.WS.NSRC.ORG    *

Now we use kadmin.local (running as root) to create the first few
principals: a host principal for the host itself (putting the
randomly-chosen key into its own keytab file); a regular principal "student"
and a KDC admin principal "student/admin"

    # kadmin.local
    addprinc -randkey host/pc1.ws.nsrc.org
    ktadd host/pc1.ws.nsrc.org
    addprinc student
    -- you'll be prompted to choose a password
    addprinc student/admin
    -- you'll be prompted to choose a password
    ^D

Now start the daemons:

    # /etc/init.d/krb5-kdc start
    # /etc/init.d/krb5-admin-server start

At this point, you should be able to get a ticket from your own realm:

    $ kinit student
    Password for student@REALM1.WS.NSRC.ORG: <enter chosen password>
    $ klist

(Note that you've obtained a ticket from your own realm, using the
username and password you created in your own KDC)

If this doesn't work, then debug as follows:

* Check your clock is synchronized (type `date`)
* Check your krb5.conf
* Check kdc is running: `ps auxwww | grep krb5kdc`
* Look at KDC logs in /var/log/auth.log

5. Managing principals
----------------------

From now on, you don't need `kadmin.local` as root to administer the
Kerberos database; you can use `kadmin` instead, as a normal user.  This
runs over a TCP socket (so it can be run from a remote workstation, not
necessarily the KDC).  The traffic is authenticated and encrypted using
Kerberos.

    $ kadmin -p student/admin
    ... enter password for 'student/admin' which you chose earlier

Type '?' for a list of commands. The important ones are:

    listprincs              -- list principals
    addprinc <principal>    -- add principal
    cpw <principal>         -- change password
    delprinc <principal>    -- delete principal

Use ^D (ctrl-D) to exit.

Try the following:

* Change the password for the `student` principal. In another screen,
  check that you can `kinit student` with the new password.
* Create a new user principal of your choice, and check you can get a ticket
  for it with kinit.

6. Kerberos ssh
---------------

Since we have modified krb5.conf earlier, restart sshd:

    # service ssh restart

Create a local `student` user:

    # useradd -m -s /bin/bash student

Note that we have not set any password. However you should be able to login
using a kerberos ticket:

    $ kinit student
    $ ssh student@localhost

7. Extra exercises
------------------

If you have spare time, you and your neighbour can add [realms] and
[domain_realms] sections for each other, and you can try to get a ticket
directly from the other realm and use it to login to the other machine:

    kinit student@REALM2.WS.NSRC.ORG
    ssh student@pc2.ws.nsrc.org

You could also try setting up cross-realm authentication. Each KDC has to
share a secret with its neighbour.  On both KDCs create the following
principals; for each principal enter the same (preferably long and complex)
passphrase on both KDCs.

    # kadmin -p student/admin
    addprinc krbtgt/REALM2.WS.NSRC.ORG@REALM1.WS.NSRC.ORG
    addprinc krbtgt/REALM1.WS.NSRC.ORG@REALM2.WS.NSRC.ORG

(The first sets up realm2 to trust realm1; the second sets up realm1 to
trust realm2)

At this point, Kerberos authentication will work, but ssh on pc1 will reject
a user who has authenticated as someone@REALM2 because pc1 is part of
REALM1.

    -- on pc1, logging in to pc2
    $ kinit student
    $ ssh -v student@pc2.ws.nsrc.org
    -- should be rejected

To permit it, create file `~/.k5login` containing the authorized
principal(s), one per line.

    -- on pc2
    # editor ~student/.k5login
    student@REALM1.WS.NSRC.ORG

Notes
-----

In a real environment, you would add at least one slave KDC for resilience.
There is information how to do this at
http://web.mit.edu/kerberos/krb5-1.8/krb5-1.8.3/doc/krb5-install.html#Install%20the%20Slave%20KDCs