moonshot/mech_eap/README

   1 Overview
   2 ========
   3
   4 This is an implementation of the GSS EAP mechanism, as described in
   5 draft-ietf-abfab-gss-eap-01.txt.
   6
   7 Building
   8 ========
   9
  10 In order to build this, a recent Kerberos implementation (MIT or
  11 Heimdal), Shibboleth, and EAP libraries are required, along with
  12 all of their dependencies.
  13
  14 Note: not all SPIs are supported by the Heimdal mechanism glue,
  15 so not all features will be available.
  16
  17 Installing
  18 ==========
  19
  20 GSS mechglue
  21 ------------
  22
  23 When installing, be sure to edit $prefix/etc/gss/mech to register
  24 the EAP mechanisms. A sample configuration file is in this directory.
  25 You may need to specify an absolute path.
  26
  27 RADIUS client library
  28 ---------------------
  29
  30 Make sure your RADIUS library is configured to talk to the server of
  31 your choice: see the example radsec.conf in this directory. If you
  32 want to use TCP or TLS, you'll need to run radsecproxy in front of
  33 your RADIUS server.
  34
  35 RADIUS server
  36 -------------
  37
  38 These instructions apply to FreeRADIUS only, which is downloadable
  39 from http://freeradius.org/. After configure, make, install, do the
  40 following:
  41
  42 On the RADIUS server side, you need to install dictionary.ukerna to
  43 $prefix/etc/raddb and include it from the main dictionary file, by
  44 adding:
  45
  46     $INCLUDE dictionary.ukerna
  47
  48 to $prefix/etc/raddb/dictionary. Make sure these files are world-
  49 readable; they weren't in my installation.
  50
  51 Edit $prefix/etc/raddb/users to add your test user and password:
  52
  53     bob@PROJECT-MOONSHOT.ORG Cleartext-Password := secret
  54
  55 Add an entry for your acceptor to $prefix/etc/raddb/clients.conf:
  56
  57     client somehost {
  58         ipaddr = 127.0.0.1
  59         secret = testing123
  60         require_message_authenticator = yes
  61     }
  62
  63 Edit $prefix/etc/raddb/eap.conf and set:
  64
  65     eap {
  66 ...
  67         default_eap_type = ttls
  68 ...
  69         tls {
  70             certdir = ...
  71             cadir = ...
  72             private_key_file = ...
  73             certificate_file = ...
  74         }
  75         ttls {
  76             default_eap_type = mschapv2
  77             copy_request_to_tunnel = no
  78             use_tunneled_reply = no
  79             virtual_server = "inner-tunnel"
  80         }
  81 ...
  82     }
  83
  84 to enable EAP-TTLS.
  85
  86 If you want the acceptor be able to identify the user, the RADIUS
  87 server needs to echo back the EAP username from the inner tunnel;
  88 for privacy, mech_eap only sends the realm in the EAP Identity
  89 response. To configure this with FreeRADIUS, add:
  90
  91     update outer.reply {
  92         User-Name = "%{request:User-Name}"
  93     }
  94
  95 If you want to add a SAML assertion, do this with "update reply"
  96 in $prefix/etc/raddb/sites-available/default:
  97
  98     update reply {
  99         SAML-AAA-Assertion = '<saml:Assertion ...'
 100         SAML-AAA-Assertion += '...'
 101     }
 102
 103 You'll need to split it into multiple lines because of the RADIUS
 104 attribute size limit.
 105
 106 Testing
 107 =======
 108
 109 You can then test the MIT or Cyrus GSS and SASL example programs.
 110 Sample usage is given below. Substitute <user>, <pass> and <host>
 111 appropriately (<host> is the name of the host running the server,
 112 not the RADIUS server).
 113
 114 % gss-client -port 5555 -spnego -mech "{1 3 6 1 4 1 5322 22 1 18}" \
 115   -user <user>@<realm> -pass <pass> <host> host@<host> \
 116   "Testing GSS EAP"
 117 % gss-server -port 5555 -export host@<host>
 118
 119 Note: for SASL you will be prompted for a username and password.
 120
 121 % client -C -p 5556 -s host -m EAP-AES128 <host>
 122 % server -c -p 5556 -s host -h <host>
 123
 124 To test fast reauthentication support, add the following to
 125 /etc/krb5.conf:
 126
 127 [appdefaults]
 128         eap_gss = {
 129                 reauth_use_ccache = TRUE
 130         }
 131
 132 This will store a Kerberos ticket for a GSS-EAP authenticated user
 133 in a credentials cache, which can then be used for re-authentication
 134 to the same acceptor. You must have a valid keytab configured.
 135
 136 In this testing phase of Moonshot, it's also possible to store a
 137 default identity and credential in a file. The format consists of
 138 the string representation of the initiator identity and the password,
 139 separated by newlines. The default location of this file is
 140 .gss_eap_id in the user's home directory, however the GSSEAP_IDENTITY
 141 environment variable can be used to set an alternate location.
 142
 143 You can also set a default realm in [appdefaults]; the Kerberos
 144 default realm is never used by mech_eap (or at least, that is the
 145 intention), so if unspecified you must always qualify names. It should
 146 generally not be necessary to specify this.
 147