1 EAP-TLS authentication support for PPP
2 ======================================
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.
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
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
20 This patch provide EAP-TLS support to pppd.
21 This authentication method can be used in both client or server
26 To build pppd with EAP-TLS support, OpenSSL (http://www.openssl.org)
27 is required. Any version from 0.9.7 should work.
29 Configure, compile, and install as usual.
33 On the client side there are two ways to configure EAP-TLS:
35 1. supply the appropriate 'ca', 'cert' and 'key' command-line parameters
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:
42 The name used by the client for authentication, can be *
44 The name of the server, can be *
45 - Client certificate file
46 The file containing the certificate chain for the
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.
53 The file containing the trusted CA certificates in PEM
55 - Client private key file
56 The file containing the client private key in PEM format.
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:
64 The name used by the client for authentication, can be *
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.
71 - Server certificate file
72 The file containing the certificate chain for the
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.
79 A list of IP addresses the client is allowed to use.
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:
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:
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
99 openssl_conf = openssl_def
102 engines = engine_section
105 pkcs11 = pkcs11_section
109 dynamic_path = /usr/lib64/openssl/engines/engine_pkcs11.so
110 MODULE_PATH = /usr/lib64/libeTPkcs11.so
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
125 These pppd options are available:
128 Use the CA public certificate found in <ca-file> in PEM format
130 Use the directory <directory> as the CA public certificate directory
132 Use the client public certificate found in <cert-file> in PEM format
133 or in engine:engine_id format
135 Use the client private key found in <key-file> in PEM format
136 or in engine:engine_id format
138 Use the Certificate Revocation List (CRL) file <crl-file> in PEM format.
140 Use CRL files from directory <dir>. It contains CRL files in PEM
141 format and each file contains a CRL. The files are looked up
142 by the issuer name hash value. Use the c_rehash utility
143 to create necessary links.
145 If the peer doesn't ask us to authenticate or doesn't use eap
146 to authenticate us, disconnect.
147 max-tls-version <1.0|1.1|1.2 (default)|1.3>
148 Specify the maximum TLS protocol version to negotiate with peers. Defaults
149 to TLSv1.2 as the TLSv1.3 code is experimental.
152 password-encrypted certificates can be used as of v0.94 of this
153 patch. The password for the eap-tls.key file is specified using
156 statement in the ppp options file, or by using the appropriate
157 plugin which supplies a 'eaptls_passwd_hook' routine.
161 If you're setting up a pppd server, edit the EAP-TLS configuration file
162 as written above and then run pppd with the 'auth' option to authenticate
163 the client. The EAP-TLS method will be used if the other eap methods can't
164 be used (no secrets).
166 If you're setting up a client, edit the configuration file and then run
167 pppd with 'remotename' option to specify the server name. Add the
168 'need-peer-eap' option if you want to be sure the peer ask you to
169 authenticate (and to use eap) and to disconnect if it doesn't.
173 The following example can be used to connect a Linux client with the 'pptp'
174 package to a Linux server running the 'pptpd' (PoPToP) package. The server
175 was configured with a certificate with name (CN) 'pptp-server', the client
176 was configured with a certificate with name (CN) 'pptp-client', both
177 signed by the same Certificate Authority (CA).
180 - /etc/pptpd.conf file:
181 option /etc/ppp/options-pptpd-eaptls
183 remoteip 172.16.1.10-20
184 - /etc/ppp/options-pptpd-eaptls file:
201 crl /home/janjust/ppp/keys/crl.pem
204 logfile /tmp/pppd.log
206 - /etc/ppp/eaptls-server file:
207 * pptp-server - /etc/ppp/pptp-server.crt /etc/ppp/ca.crt /etc/ppp/pptp-server.key *
210 pptdp --conf /etc/pptpd.conf
214 pppd noauth require-eap require-mppe-128 \
215 ipcp-accept-local ipcp-accept-remote noipdefault \
216 cert /etc/ppp/keys/pptp-client.crt \
217 key /etc/ppp/keys/pptp-client.key \
218 ca /etc/ppp/keys/ca.crt \
219 name pptp-client remotename pptp-server \
220 debug logfile /tmp/pppd.log
221 pty "pptp pptp-server.example.com --nolaunchpppd"
223 Check /var/log/messages and the files /tmp/pppd.log on both sides for debugging info.
227 This is experimental code.
228 Send suggestions and comments to Jan Just Keijser <janjust@nikhef.nl>