| 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> | |