Overview
========

This is an implementation of the GSS EAP mechanism, as described in
draft-ietf-abfab-gss-eap-01.txt.

Building
========

In order to build this, a recent Kerberos implementation (MIT or
Heimdal), Shibboleth, and EAP libraries are required, along with
all of their dependencies.

Note: not all SPIs are supported by the Heimdal mechanism glue,
so not all features will be available.

Installing
==========

GSS mechglue
------------

When installing, be sure to edit $prefix/etc/gss/mech to register
the EAP mechanisms. A sample configuration file is in this directory.
You may need to specify an absolute path.

RADIUS client library
---------------------

Make sure your RADIUS library is configured to talk to the server of
your choice: see the example radsec.conf in this directory. If you
want to use TCP or TLS, you'll need to run radsecproxy in front of
your RADIUS server.

RADIUS server
-------------

These instructions apply to FreeRADIUS only, which is downloadable
from http://freeradius.org/. After configure, make, install, do the
following:

On the RADIUS server side, you need to install dictionary.ukerna to
$prefix/etc/raddb and include it from the main dictionary file, by
adding:

    $INCLUDE dictionary.ukerna

to $prefix/etc/raddb/dictionary. Make sure these files are world-
readable; they weren't in my installation.

Edit $prefix/etc/raddb/users to add your test user and password:

    bob@PROJECT-MOONSHOT.ORG Cleartext-Password := secret

Add an entry for your acceptor to $prefix/etc/raddb/clients.conf:

    client somehost {
        ipaddr = 127.0.0.1
        secret = testing123
        require_message_authenticator = yes
    }

Edit $prefix/etc/raddb/eap.conf and set:

    eap {
...
        default_eap_type = ttls
...
        tls {
            certdir = ...
            cadir = ...
            private_key_file = ...
            certificate_file = ...
        }
        ttls {
            default_eap_type = mschapv2
            copy_request_to_tunnel = no
            use_tunneled_reply = no
            virtual_server = "inner-tunnel"
        }
...
    }

to enable EAP-TTLS.

If you want the acceptor be able to identify the user, the RADIUS
server needs to echo back the EAP username from the inner tunnel;
for privacy, mech_eap only sends the realm in the EAP Identity
response. To configure this with FreeRADIUS, add:

    update outer.reply {
        User-Name = "%{request:User-Name}"
    }

If you want to add a SAML assertion, do this with "update reply"
in $prefix/etc/raddb/sites-available/default:

    update reply {
        SAML-AAA-Assertion = '<saml:Assertion ...'
        SAML-AAA-Assertion += '...'
    }

You'll need to split it into multiple lines because of the RADIUS
attribute size limit.

Testing
=======

You can then test the MIT or Cyrus GSS and SASL example programs.
Sample usage is given below. Substitute <user>, <pass> and <host>
appropriately (<host> is the name of the host running the server,
not the RADIUS server).

% gss-client -port 5555 -spnego -mech "{1 3 6 1 5 5 15 1 1 18}" \
  -user <user>@<realm> -pass <pass> <host> host@<host> \
  "Testing GSS EAP"
% gss-server -port 5555 -export host@<host>

Note: for SASL you will be prompted for a username and password.

% client -C -p 5556 -s host -m EAP-AES128 <host>
% server -c -p 5556 -s host -h <host>

To test fast reauthentication support, add the following to
/etc/krb5.conf:

[appdefaults]
        eap_gss = {
                reauth_use_ccache = TRUE
        }

This will store a Kerberos ticket for a GSS-EAP authenticated user
in a credentials cache, which can then be used for re-authentication
to the same acceptor. You must have a valid keytab configured.

In this testing phase of Moonshot, it's also possible to store a
default identity and credential in a file. The format consists of
the string representation of the initiator identity and the password,
separated by newlines. The default location of this file is
.gss_eap_id in the user's home directory, however the GSSEAP_IDENTITY
environment variable can be used to set an alternate location.

You can also set a default realm in [appdefaults]; the Kerberos
default realm is never used by mech_eap (or at least, that is the
intention), so if unspecified you must always qualify names. It should
generally not be necessary to specify this.