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: : 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: : 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 Use the CA public certificate found in in PEM format capath Use the directory as the CA public certificate directory cert Use the client public certificate found in in PEM format or in engine:engine_id format key Use the client private key found in in PEM format or in engine:engine_id format pkcs12 Use a pkcs12 envelope as a substitute for cert and key. A password may be required to use this file. crl Use the Certificate Revocation List (CRL) file in PEM format. crl-dir Use CRL files from directory . 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. tls-verify-key-usage Validate certificate purpose and extended key usage tls-verify-method Compare the remotename against the subject, certificate name, or match by suffix. Default is 'name'. 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