README.eap-tls

   1 EAP-TLS authentication support for PPP
   2 ======================================
   3
   4 1. Intro
   5
   6     The Extensible Authentication Protocol (EAP; RFC 3748) is a
   7     security protocol that can be used with PPP.  It provides a means
   8     to plug in multiple optional authentication methods.
   9
  10     Transport Level Security (TLS; RFC 5216) provides for mutual
  11     authentication, integrity-protected ciphersuite negotiation and
  12     key exchange between two endpoints.  It also provides for optional
  13     MPPE encryption.
  14
  15     EAP-TLS (RFC 2716) incapsulates the TLS messages in EAP packets,
  16     allowing TLS mutual authentication to be used as a generic EAP
  17     mechanism. It also provides optional encryption using the MPPE
  18     protocol.
  19
  20     This patch provide EAP-TLS support to pppd.
  21     This authentication method can be used in both client or server
  22     mode.
  23
  24 2. Building
  25
  26     To build pppd with EAP-TLS support, OpenSSL (http://www.openssl.org)
  27     is required. Any version from 0.9.7 should work.
  28
  29     Configure, compile, and install as usual.
  30
  31 3. Configuration
  32
  33     On the client side there are two ways to configure EAP-TLS:
  34
  35     1. supply the appropriate 'ca', 'cert' and 'key' command-line parameters
  36
  37     2. edit the /etc/ppp/eaptls-client file.
  38     Insert a line for each system with which you use EAP-TLS.
  39     The line is composed of this fields separated by tab:
  40
  41       - Client name
  42         The name used by the client for authentication, can be *
  43       - Server name
  44         The name of the server, can be *
  45       - Client certificate file
  46         The file containing the certificate chain for the
  47         client in PEM format
  48       - Server certificate file
  49         If you want to specify the certificate that the
  50         server is allowed to use, put the certificate file name.
  51         Else put a dash '-'.
  52       - CA certificate file
  53         The file containing the trusted CA certificates in PEM
  54         format.
  55       - Client private key file
  56         The file containing the client private key in PEM format.
  57
  58
  59     On the server side edit the /etc/ppp/eaptls-server file.
  60     Insert a line for each system with which you use EAP-TLS.
  61     The line is composed of this fields separated by tab:
  62
  63       - Client name
  64         The name used by the client for authentication, can be *
  65       - Server name
  66         The name of the server, can be *
  67       - Client certificate file
  68         If you want to specify the certificate that the
  69         client is allowed to use, put the certificate file name.
  70         Else put a dash '-'.
  71       - Server certificate file
  72         The file containing the certificate chain for the
  73         server in PEM format
  74       - CA certificate file
  75         The file containing the trusted CA certificates in PEM format.
  76       - Client private key file
  77         The file containing the server private key in PEM format.
  78       - addresses
  79         A list of IP addresses the client is allowed to use.
  80
  81
  82     OpenSSL engine support is included starting with v0.95 of this patch.
  83     Currently the only engine tested is the 'pkcs11' engine (hardware token
  84     support). To use the 'pksc11' engine:
  85       - Use a special private key fileiname in the /etc/ppp/eaptls-client file:
  86           <engine>:<identifier>
  87         e.g.
  88           pkcs11:123456
  89
  90       - The certificate can also be loaded from the 'pkcs11' engine using
  91         a special client certificate filename in the /etc/ppp/eaptls-client file:
  92           <engine>:<identifier>
  93         e.g.
  94           pkcs11:123456
  95
  96       - Create an /etc/ppp/openssl.cnf file to load the right OpenSSL engine prior
  97         to starting 'pppd'. A sample openssl.cnf file is
  98
  99         openssl_conf = openssl_def
 100
 101         [ openssl_def ]
 102         engines = engine_section
 103
 104         [ engine_section ]
 105         pkcs11 = pkcs11_section
 106
 107         [ pkcs11_section ]
 108         engine_id = pkcs11
 109         dynamic_path = /usr/lib64/openssl/engines/engine_pkcs11.so
 110         MODULE_PATH = /usr/lib64/libeTPkcs11.so
 111         init = 0
 112
 113       - There are two ways to specify a password/PIN for the PKCS11 engine:
 114           - inside the openssl.cnf file using
 115               PIN = your-secret-pin
 116             Note The keyword 'PIN' is case sensitive!
 117           - Using the 'password' in the ppp options file.
 118         From v0.97 of the eap-tls patch the password can also be supplied
 119         using the appropriate 'eaptls_passwd_hook' (see plugins/passprompt.c
 120         for an example).
 121
 122
 123 4. Options
 124
 125     These pppd options are available:
 126
 127       ca <ca-file>
 128         Use the CA public certificate found in <ca-file> in PEM format
 129       capath <directory>
 130         Use the directory <directory> as the CA public certificate directory
 131       cert <cert-file>
 132         Use the client public certificate found in <cert-file> in PEM format
 133         or in engine:engine_id format
 134       key <key-file>
 135         Use the client private key found in <key-file> in PEM format
 136         or in engine:engine_id format
 137       pkcs12 <pkcs12-file>
 138         Use a pkcs12 envelope as a substitute for cert and key. A password may be
 139         required to use this file.
 140       crl <crl-file>
 141         Use the Certificate Revocation List (CRL) file <crl-file> in PEM format.
 142       crl-dir <dir>
 143         Use CRL files from directory <dir>. It contains CRL files in PEM
 144         format and each file contains a CRL. The files are looked up
 145         by the issuer name hash value. Use the c_rehash utility
 146         to create necessary links.
 147       need-peer-eap
 148         If the peer doesn't ask us to authenticate or doesn't use eap
 149         to authenticate us, disconnect.
 150       max-tls-version <1.0|1.1|1.2 (default)|1.3>
 151         Specify the maximum TLS protocol version to negotiate with peers. Defaults
 152         to TLSv1.2 as the TLSv1.3 code is experimental.
 153       tls-verify-key-usage
 154         Validate certificate purpose and extended key usage
 155       tls-verify-method <none|subject|name|suffix>
 156         Compare the remotename against the subject, certificate name, or
 157         match by suffix. Default is 'name'.
 158
 159     Note:
 160       password-encrypted certificates can be used as of v0.94 of this
 161       patch. The password for the eap-tls.key file is specified using
 162       the regular
 163           password ....
 164       statement in the ppp options file, or by using the appropriate
 165       plugin which supplies a 'eaptls_passwd_hook' routine.
 166
 167 5. Connecting
 168
 169     If you're setting up a pppd server, edit the EAP-TLS configuration file
 170     as written above and then run pppd with the 'auth' option to authenticate
 171     the client. The EAP-TLS method will be used if the other eap methods can't
 172     be used (no secrets).
 173
 174     If you're setting up a client, edit the configuration file and then run
 175     pppd with 'remotename' option to specify the server name. Add the
 176     'need-peer-eap' option if you want to be sure the peer ask you to
 177     authenticate (and to use eap) and to disconnect if it doesn't.
 178
 179 6. Example
 180
 181     The following example can be used to connect a Linux client with the 'pptp'
 182     package to a Linux server running the 'pptpd' (PoPToP) package. The server
 183     was configured with a certificate with name (CN) 'pptp-server', the client
 184     was configured with a certificate with name (CN) 'pptp-client', both
 185     signed by the same Certificate Authority (CA).
 186
 187     Server side:
 188       - /etc/pptpd.conf file:
 189           option /etc/ppp/options-pptpd-eaptls
 190           localip 172.16.1.1
 191           remoteip 172.16.1.10-20
 192       - /etc/ppp/options-pptpd-eaptls file:
 193           name pptp-server
 194           lock
 195           mtu 1500
 196           mru 1450
 197           auth
 198           lcp-echo-failure 3
 199           lcp-echo-interval 5
 200           nodeflate
 201           nobsdcomp
 202           nopredictor1
 203           nopcomp
 204           noaccomp
 205
 206           require-eap
 207           require-mppe-128
 208
 209           crl /home/janjust/ppp/keys/crl.pem
 210
 211           debug
 212           logfile /tmp/pppd.log
 213
 214       - /etc/ppp/eaptls-server file:
 215            * pptp-server - /etc/ppp/pptp-server.crt /etc/ppp/ca.crt /etc/ppp/pptp-server.key *
 216
 217       - On the server, run
 218           pptdp --conf /etc/pptpd.conf
 219
 220     Client side:
 221       - Run
 222           pppd noauth require-eap require-mppe-128 \
 223             ipcp-accept-local ipcp-accept-remote noipdefault \
 224             cert  /etc/ppp/keys/pptp-client.crt \
 225             key   /etc/ppp/keys/pptp-client.key \
 226             ca    /etc/ppp/keys/ca.crt \
 227             name pptp-client remotename pptp-server \
 228             debug logfile /tmp/pppd.log
 229             pty "pptp pptp-server.example.com --nolaunchpppd"
 230
 231     Check /var/log/messages and the files /tmp/pppd.log on both sides for debugging info.
 232
 233 7. Notes
 234
 235     This is experimental code.
 236     Send suggestions and comments to Jan Just Keijser <janjust@nikhef.nl>
 237