Add support for EAP-TLS (including experimental TLS v1.3 support).

Signed-off-by: Jan Just Keijser <jan.just.keijser@gmail.com>

1 files changed, 229 insertions, 0 deletions

diff --git a/README.eap-tls b/README.eap-tls
new file mode 100644
index 0000000..ab3794e
--- /dev/null
+++ b/README.eap-tls
@@ -0,0 +1,229 @@
+EAP-TLS authentication support for PPP
+======================================
+
+1. Intro
+
+    The Extensible Authentication Protocol (EAP; RFC 3748) is a
+    security protocol that can be used with PPP.  It provides a means
+    to plug in multiple optional authentication methods.
+
+    Transport Level Security (TLS; RFC 5216) provides for mutual 
+    authentication, integrity-protected ciphersuite negotiation and 
+    key exchange between two endpoints.  It also provides for optional
+    MPPE encryption.
+
+    EAP-TLS (RFC 2716) incapsulates the TLS messages in EAP packets,
+    allowing TLS mutual authentication to be used as a generic EAP
+    mechanism. It also provides optional encryption using the MPPE
+    protocol.
+
+    This patch provide EAP-TLS support to pppd.
+    This authentication method can be used in both client or server
+    mode.
+
+2. Building
+
+    To build pppd with EAP-TLS support, OpenSSL (http://www.openssl.org)
+    is required. Any version from 0.9.7 should work.
+    
+    Configure, compile, and install as usual. 
+
+3. Configuration
+
+    On the client side there are two ways to configure EAP-TLS:
+
+    1. supply the appropriate 'ca', 'cert' and 'key' command-line parameters
+
+    2. edit the /etc/ppp/eaptls-client file.
+    Insert a line for each system with which you use EAP-TLS.
+    The line is composed of this fields separated by tab:
+
+      - Client name 
+        The name used by the client for authentication, can be *
+      - Server name
+        The name of the server, can be *
+      - Client certificate file 
+        The file containing the certificate chain for the 
+        client in PEM format
+      - Server certificate file
+        If you want to specify the certificate that the 
+        server is allowed to use, put the certificate file name.
+        Else put a dash '-'.
+      - CA certificate file
+        The file containing the trusted CA certificates in PEM
+        format.
+      - Client private key file
+        The file containing the client private key in PEM format.
+
+
+    On the server side edit the /etc/ppp/eaptls-server file.
+    Insert a line for each system with which you use EAP-TLS.
+    The line is composed of this fields separated by tab:
+
+      - Client name
+        The name used by the client for authentication, can be *
+      - Server name
+        The name of the server, can be *
+      - Client certificate file
+        If you want to specify the certificate that the
+        client is allowed to use, put the certificate file name.
+        Else put a dash '-'.
+      - Server certificate file
+        The file containing the certificate chain for the
+        server in PEM format
+      - CA certificate file
+        The file containing the trusted CA certificates in PEM format.
+      - Client private key file
+        The file containing the server private key in PEM format.
+      - addresses
+        A list of IP addresses the client is allowed to use.
+
+
+    OpenSSL engine support is included starting with v0.95 of this patch. 
+    Currently the only engine tested is the 'pkcs11' engine (hardware token
+    support). To use the 'pksc11' engine:
+      - Use a special private key fileiname in the /etc/ppp/eaptls-client file:
+          <engine>:<identifier>
+        e.g.
+          pkcs11:123456
+
+      - The certificate can also be loaded from the 'pkcs11' engine using
+        a special client certificate filename in the /etc/ppp/eaptls-client file:
+          <engine>:<identifier>
+        e.g.
+          pkcs11:123456
+
+      - Create an /etc/ppp/openssl.cnf file to load the right OpenSSL engine prior
+        to starting 'pppd'. A sample openssl.cnf file is
+
+        openssl_conf = openssl_def
+
+        [ openssl_def ]
+        engines = engine_section
+
+        [ engine_section ]
+        pkcs11 = pkcs11_section
+
+        [ pkcs11_section ]
+        engine_id = pkcs11
+        dynamic_path = /usr/lib64/openssl/engines/engine_pkcs11.so
+        MODULE_PATH = /usr/lib64/libeTPkcs11.so
+        init = 0
+
+      - There are two ways to specify a password/PIN for the PKCS11 engine:
+          - inside the openssl.cnf file using
+              PIN = your-secret-pin
+            Note The keyword 'PIN' is case sensitive!
+          - Using the 'password' in the ppp options file.
+        From v0.97 of the eap-tls patch the password can also be supplied
+        using the appropriate 'eaptls_passwd_hook' (see plugins/passprompt.c
+        for an example).
+
+
+4. Options
+
+    These pppd options are available:
+
+      ca <ca-file>
+        Use the CA public certificate found in <ca-file> in PEM format
+      ca-path <directory>
+        Use the directory <directory> as the CA public certificate directory
+      cert <cert-file>
+        Use the client public certificate found in <cert-file> in PEM format
+        or in engine:engine_id format
+      key <key-file>
+        Use the client private key found in <key-file> in PEM format
+        or in engine:engine_id format
+      crl <crl-file>
+        Use the Certificate Revocation List (CRL) file <crl-file> in PEM format.
+      crl-dir <dir>
+        Use CRL files from directory <dir>. It contains CRL files in PEM
+        format and each file contains a CRL. The files are looked up 
+        by the issuer name hash value. Use the c_rehash utility 
+        to create necessary links.
+      need-peer-eap
+        If the peer doesn't ask us to authenticate or doesn't use eap
+        to authenticate us, disconnect.
+      max-tls-version <1.0|1.1|1.2 (default)|1.3>
+        Specify the maximum TLS protocol version to negotiate with peers. Defaults
+        to TLSv1.2 as the TLSv1.3 code is experimental.
+
+    Note: 
+      password-encrypted certificates can be used as of v0.94 of this 
+      patch. The password for the eap-tls.key file is specified using 
+      the regular
+          password ....
+      statement in the ppp options file, or by using the appropriate
+      plugin which supplies a 'eaptls_passwd_hook' routine.
+
+5. Connecting
+
+    If you're setting up a pppd server, edit the EAP-TLS configuration file 
+    as written above and then run pppd with the 'auth' option to authenticate
+    the client. The EAP-TLS method will be used if the other eap methods can't
+    be used (no secrets).
+
+    If you're setting up a client, edit the configuration file and then run
+    pppd with 'remotename' option to specify the server name. Add the 
+    'need-peer-eap' option if you want to be sure the peer ask you to
+    authenticate (and to use eap) and to disconnect if it doesn't.
+
+6. Example
+
+    The following example can be used to connect a Linux client with the 'pptp'
+    package to a Linux server running the 'pptpd' (PoPToP) package. The server
+    was configured with a certificate with name (CN) 'pptp-server', the client
+    was configured with a certificate with name (CN) 'pptp-client', both 
+    signed by the same Certificate Authority (CA).
+
+    Server side:
+      - /etc/pptpd.conf file:
+          option /etc/ppp/options-pptpd-eaptls
+          localip 172.16.1.1
+          remoteip 172.16.1.10-20 
+      - /etc/ppp/options-pptpd-eaptls file:
+          name pptp-server
+          lock 
+          mtu 1500 
+          mru 1450
+          auth 
+          lcp-echo-failure 3 
+          lcp-echo-interval 5 
+          nodeflate 
+          nobsdcomp
+          nopredictor1
+          nopcomp
+          noaccomp
+          
+          require-eap
+          require-mppe-128
+          
+          crl /home/janjust/ppp/keys/crl.pem
+          
+          debug
+          logfile /tmp/pppd.log
+
+      - /etc/ppp/eaptls-server file:
+           * pptp-server - /etc/ppp/pptp-server.crt /etc/ppp/ca.crt /etc/ppp/pptp-server.key *
+
+      - On the server, run 
+          pptdp --conf /etc/pptpd.conf
+       
+    Client side:
+      - Run
+          pppd noauth require-eap require-mppe-128 \
+            ipcp-accept-local ipcp-accept-remote noipdefault \
+            cert  /etc/ppp/keys/pptp-client.crt \
+            key   /etc/ppp/keys/pptp-client.key \
+            ca    /etc/ppp/keys/ca.crt \
+            name pptp-client remotename pptp-server \
+            debug logfile /tmp/pppd.log
+            pty "pptp pptp-server.example.com --nolaunchpppd"
+
+    Check /var/log/messages and the files /tmp/pppd.log on both sides for debugging info.
+
+7. Notes
+
+    This is experimental code.
+    Send suggestions and comments to Jan Just Keijser <janjust@nikhef.nl>
+