X-Git-Url: http://www.project-moonshot.org/gitweb/?a=blobdiff_plain;f=README;h=3cb2d50230d49744f23fb3e5b973742fd036f292;hb=refs%2Fheads%2Fjson-name;hp=bd68ef845e0d4953e73918152d988f2f74a0b310;hpb=31cef49681566dc99790812f31de834dfce02c74;p=mech_eap.orig

diff --git a/README b/README
index bd68ef8..3cb2d50 100644
--- a/README
+++ b/README
@@ -1,6 +1,147 @@
+Overview
+========
+
 This is an implementation of the GSS EAP mechanism, as described in
-draft-howlett-eap-gss-xx.txt.
+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 4 1 5322 22 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.
+