README.eap-srp

   1 EAP with MD5-Challenge and SRP-SHA1 support
   2 by James Carlson, Sun Microsystems
   3 Version 2, September 22nd, 2002
   4
   5
   6 1.  What it does
   7
   8     The Extensible Authentication Protocol (EAP; RFC 2284) is a
   9     security protocol that can be used with PPP.  It provides a means
  10     to plug in multiple optional authentication methods.
  11
  12     This implementation includes the required default MD5-Challenge
  13     method, which is similar to CHAP (RFC 1994), as well as the new
  14     SRP-SHA1 method.  This latter method relies on an exchange that is
  15     not vulnerable to dictionary attacks (as is CHAP), does not
  16     require the server to keep a cleartext copy of the secret (as in
  17     CHAP), supports identity privacy, and produces a temporary shared
  18     key that could be used for data encryption.
  19
  20     The SRP-SHA1 method is based on draft-ietf-pppext-eap-srp-03.txt,
  21     a work in progress.
  22
  23 2.  Required libraries
  24
  25     Two other packages are required first.  Download and install
  26     OpenSSL and Thomas Wu's SRP implementation.
  27
  28         http://www.openssl.org/ (or ftp://ftp.openssl.org/source/)
  29         http://srp.stanford.edu/
  30
  31     Follow the directions in each package to install the SSL and SRP
  32     libraries.  Once SRP is installed, you may run tconf as root to
  33     create known fields, if desired.  (This step is not required.)
  34
  35 3.  Installing the patch
  36
  37     The EAP-SRP patch described here is integrated into this version
  38     of pppd.  The following patch may be used with older pppd sources:
  39
  40         ftp://playground.sun.com/carlsonj/eap/ppp-2.4.1-eap-1.tar.gz
  41
  42     Configure, compile, and install as root.  You may want to edit
  43     pppd/Makefile after configuring to enable or disable optional
  44     features.
  45
  46         % ./configure
  47         % make
  48         % su
  49         # make install
  50
  51     If you use csh or tcsh, run "rehash" to pick up the new commands.
  52
  53     If you're using Solaris, and you run into trouble with the
  54     pseudonym feature on the server side ("no DES here" shows in the
  55     log file), make sure that you have the "domestic" versions of the
  56     DES libraries linked.  You should see "crypt_d" in "ldd
  57     /usr/local/bin/pppd".  If you see "crypt_i" instead, then make
  58     sure that /usr/lib/libcrypt.* links to /usr/lib/libcrypt_d.*.  (If
  59     you have the international version of Solaris, then you won't have
  60     crypt_d.  You might want to find an alternative DES library.)
  61
  62 4.  Adding the secrets
  63
  64     On the EAP SRP-SHA1 client side, access to the cleartext secret is
  65     required.  This can be done in two ways:
  66
  67         - Enter the client name, server name, and password in the
  68           /etc/ppp/srp-secrets file.  This file has the same format as
  69           the existing chap-secrets and pap-secrets files.
  70
  71           clientname servername "secret here"
  72
  73         - Use the "password" option in any of the standard
  74           configuration files (or the command line) to specify the
  75           secret.
  76
  77           password "secret here"
  78
  79     On the EAP SRP-SHA1 server side, a secret verifier is required.
  80     This is a one-way hash of the client's name and password.  To
  81     generate this value, run the srp-entry program (see srp-entry(8)).
  82     This program prompts for the client name and the passphrase (the
  83     secret).  The output will be an entry, such as the following,
  84     suitable for use in the server's srp-secrets file.  Note that if
  85     this is transferred by cut-and-paste, the entry must be a single
  86     line of text in the file.
  87
  88 pppuser srpserver 0:LFDpwg4HBLi4/kWByzbZpW6pE95/iIWBSt7L.DAkHsvwQphtiq0f6reoUy/1LC1qYqjcrV97lCDmQHQd4KIACGgtkhttLdP3KMowvS0wLXLo25FPJeG2sMAUEWu/HlJPn2/gHyh9aT.ZxUs5MsoQ1E61sJkVBc.2qze1CdZiQGTK3qtWRP6DOpM1bfhKtPoVm.g.MiCcTMWzc54xJUIA0mgKtpthE3JrqCc81cXUt4DYi5yBzeeGTqrI0z2/Gj8Jp7pS4Fkq3GmnYjMxnKfQorFXNwl3m7JSaPa8Gj9/BqnorJOsnSMlIhBe6dy4CYytuTbNb4Wv/nFkmSThK782V:2cIyMp1yKslQgE *
  89
  90     The "secret" field consists of three entries separated by colons.
  91     The first entry is the index of the modulus and generator from
  92     SRP's /etc/tpasswd.conf.  If the special value 0 is used, then the
  93     well-known modulus/generator value is used (this is recommended,
  94     because it is much faster).  The second value is the verifier
  95     value.  The third is the password "salt."  These latter two values
  96     are encoded in base64 notation.
  97
  98     For EAP MD5-Challenge, both client and server use the existing
  99     /etc/ppp/chap-secrets file.
 100
 101 5.  Configuration options
 102
 103     There are two main options relating to EAP available for the
 104     client.  These are:
 105
 106         refuse-eap              - refuse to authenticate with EAP
 107         srp-use-pseudonym       - use the identity privacy if
 108                                   offered by server
 109
 110     The second option stores a pseudonym, if offered by the EAP
 111     SRP-SHA1 server, in the $HOME/.ppp_pseudonym file.  The pseudonym
 112     is typically an encrypted version of the client identity.  During
 113     EAP start-up, the pseudonym stored in this file is offered to the
 114     peer as the identity.  If this is accepted by the peer, then
 115     eavesdroppers will be unable to determine the identity of the
 116     client.  Each time the client is authenticated, the server will
 117     offer a new pseudoname to the client using an obscured (reversibly
 118     encrypted) message.  Thus, access across successive sessions
 119     cannot be tracked.
 120
 121     There are two main options for EAP on the server:
 122
 123         require-eap             - require client to use EAP
 124         srp-pn-secret "string"  - set server's pseudoname secret
 125
 126     The second option sets the long-term secret used on the server to
 127     encrypt the user's identity to produce pseudonames.  The
 128     pseudoname is constructed by hashing this string with the current
 129     date (to the nearest day) with SHA1, then using this hash as the
 130     key for a DES encryption of the client's name.  The date is added
 131     to the hash for two reasons.  First, this allows the pseudonym to
 132     change daily.  Second, it allows the server to decode any previous
 133     pseudonym by trying previous dates.
 134
 135     See the pppd(8) man page for additional options.
 136
 137 6.  Comments welcome!
 138
 139     This is still an experimental implementation.  It has been tested
 140     and reviewed carefully for correctness, but may still be
 141     incomplete or have other flaws.  All comments are welcome.  Please
 142     address them to the author:
 143
 144                 james.d.carlson@sun.com
 145
 146     or, for EAP itself or the SRP extensions to EAP, to the IETF PPP
 147     Extensions working group:
 148
 149                 ietf-ppp@merit.edu