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 a pkcs12 envelope as a substitute for cert and key. A password may be
139 required to use this file.
141 Use the Certificate Revocation List (CRL) file <crl-file> in PEM format.
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.
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.
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'.
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
164 statement in the ppp options file, or by using the appropriate
165 plugin which supplies a 'eaptls_passwd_hook' routine.
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).
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.
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).
188 - /etc/pptpd.conf file:
189 option /etc/ppp/options-pptpd-eaptls
191 remoteip 172.16.1.10-20
192 - /etc/ppp/options-pptpd-eaptls file:
209 crl /home/janjust/ppp/keys/crl.pem
212 logfile /tmp/pppd.log
214 - /etc/ppp/eaptls-server file:
215 * pptp-server - /etc/ppp/pptp-server.crt /etc/ppp/ca.crt /etc/ppp/pptp-server.key *
218 pptdp --conf /etc/pptpd.conf
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"
231 Check /var/log/messages and the files /tmp/pppd.log on both sides for debugging info.
235 This is experimental code.
236 Send suggestions and comments to Jan Just Keijser <janjust@nikhef.nl>