HEADS UP: move dictionary file to $prefix/etc/raddb/dictionary

[mech_eap.orig] / README

diff --git a/README b/README
index b0cdaeb..e9fa860 100644 (file)
--- a/README
+++ b/README
@@ -2,7 +2,7 @@ Overview
 ========
 
 This is an implementation of the GSS EAP mechanism, as described in
-draft-howlett-eap-gss-xx.txt.
+draft-ietf-abfab-gss-eap-00.txt.
 
 Building
 ========
@@ -11,6 +11,9 @@ 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
 ==========
 
@@ -18,7 +21,77 @@ When installing, be sure to edit $prefix/etc/gss/mech to register
 the EAP mechanisms. A sample configuration file is in this directory.
 
 Make sure your RADIUS library is configured to talk to the server of
-your choice.
+your choice: see the example radsec.conf in this directory.
+
+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}"
+        }
+
+to $prefix/etc/raddb/sites-enabled/inner-tunnel, and ensure that
+
+    virtual_server = "inner-tunnel"
+
+is set in eap.conf for the desired EAP types.
+
+To test the SAML assertion code path, you can place a fixed SAML
+assertion in the update reply block of the default configuration.
+
+        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
 =======
@@ -28,7 +101,7 @@ 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 4 1 5322 21 1 18}" \
+% gss-client -port 5555 -spnego -mech "{1 3 6 1 4 1 5322 22 1 18}" \
   -user <user> -pass <pass> <host> host@<host> "Testing GSS EAP"
 % gss-server -port 5555 -export host@<host>