blob: ad81ab25fbcd443369252b54bd3a74a4b4ca7b92 [file] [log] [blame]
xf.li84027492024-04-09 00:17:51 -07001EAP-TLS authentication support for PPP
2======================================
3
41. Intro
5
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.
9
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
13 MPPE encryption.
14
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
18 protocol.
19
20 This patch provide EAP-TLS support to pppd.
21 This authentication method can be used in both client or server
22 mode.
23
242. Building
25
26 To build pppd with EAP-TLS support, OpenSSL (http://www.openssl.org)
27 is required. Any version from 0.9.7 should work.
28
29 Configure, compile, and install as usual.
30
313. Configuration
32
33 On the client side there are two ways to configure EAP-TLS:
34
35 1. supply the appropriate 'ca', 'cert' and 'key' command-line parameters
36
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:
40
41 - Client name
42 The name used by the client for authentication, can be *
43 - Server name
44 The name of the server, can be *
45 - Client certificate file
46 The file containing the certificate chain for the
47 client in PEM format
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.
51 Else put a dash '-'.
52 - CA certificate file
53 The file containing the trusted CA certificates in PEM
54 format.
55 - Client private key file
56 The file containing the client private key in PEM format.
57
58
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:
62
63 - Client name
64 The name used by the client for authentication, can be *
65 - Server name
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.
70 Else put a dash '-'.
71 - Server certificate file
72 The file containing the certificate chain for the
73 server in PEM format
74 - CA certificate file
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.
78 - addresses
79 A list of IP addresses the client is allowed to use.
80
81
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:
86 <engine>:<identifier>
87 e.g.
88 pkcs11:123456
89
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:
92 <engine>:<identifier>
93 e.g.
94 pkcs11:123456
95
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
98
99 openssl_conf = openssl_def
100
101 [ openssl_def ]
102 engines = engine_section
103
104 [ engine_section ]
105 pkcs11 = pkcs11_section
106
107 [ pkcs11_section ]
108 engine_id = pkcs11
109 dynamic_path = /usr/lib64/openssl/engines/engine_pkcs11.so
110 MODULE_PATH = /usr/lib64/libeTPkcs11.so
111 init = 0
112
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
120 for an example).
121
122
1234. Options
124
125 These pppd options are available:
126
127 ca <ca-file>
128 Use the CA public certificate found in <ca-file> in PEM format
129 capath <directory>
130 Use the directory <directory> as the CA public certificate directory
131 cert <cert-file>
132 Use the client public certificate found in <cert-file> in PEM format
133 or in engine:engine_id format
134 key <key-file>
135 Use the client private key found in <key-file> in PEM format
136 or in engine:engine_id format
137 pkcs12 <pkcs12-file>
138 Use a pkcs12 envelope as a substitute for cert and key. A password may be
139 required to use this file.
140 crl <crl-file>
141 Use the Certificate Revocation List (CRL) file <crl-file> in PEM format.
142 crl-dir <dir>
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.
147 need-peer-eap
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.
153 tls-verify-key-usage
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'.
158
159 Note:
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
162 the regular
163 password ....
164 statement in the ppp options file, or by using the appropriate
165 plugin which supplies a 'eaptls_passwd_hook' routine.
166
1675. Connecting
168
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).
173
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.
178
1796. Example
180
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).
186
187 Server side:
188 - /etc/pptpd.conf file:
189 option /etc/ppp/options-pptpd-eaptls
190 localip 172.16.1.1
191 remoteip 172.16.1.10-20
192 - /etc/ppp/options-pptpd-eaptls file:
193 name pptp-server
194 lock
195 mtu 1500
196 mru 1450
197 auth
198 lcp-echo-failure 3
199 lcp-echo-interval 5
200 nodeflate
201 nobsdcomp
202 nopredictor1
203 nopcomp
204 noaccomp
205
206 require-eap
207 require-mppe-128
208
209 crl /home/janjust/ppp/keys/crl.pem
210
211 debug
212 logfile /tmp/pppd.log
213
214 - /etc/ppp/eaptls-server file:
215 * pptp-server - /etc/ppp/pptp-server.crt /etc/ppp/ca.crt /etc/ppp/pptp-server.key *
216
217 - On the server, run
218 pptdp --conf /etc/pptpd.conf
219
220 Client side:
221 - Run
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"
230
231 Check /var/log/messages and the files /tmp/pppd.log on both sides for debugging info.
232
2337. Notes
234
235 This is experimental code.
236 Send suggestions and comments to Jan Just Keijser <janjust@nikhef.nl>
237