pppd: Fix IPv6 compatibility with older kernel versions (#301)
[ppp.git] / README.eap-tls
1 EAP-TLS authentication support for PPP
2 ======================================
3
4 1. 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
24 2. 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
31 3. 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
123 4. 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       crl <crl-file>
138         Use the Certificate Revocation List (CRL) file <crl-file> in PEM format.
139       crl-dir <dir>
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.
144       need-peer-eap
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.
150       tls-verify-key-usage
151         Validate certificate purpose and extended key usage
152       tls-verify-method <none|subject|name|suffix>
153         Compare the remotename against the subject, certificate name, or
154         match by suffix. Default is 'name'.
155
156     Note: 
157       password-encrypted certificates can be used as of v0.94 of this 
158       patch. The password for the eap-tls.key file is specified using 
159       the regular
160           password ....
161       statement in the ppp options file, or by using the appropriate
162       plugin which supplies a 'eaptls_passwd_hook' routine.
163
164 5. Connecting
165
166     If you're setting up a pppd server, edit the EAP-TLS configuration file 
167     as written above and then run pppd with the 'auth' option to authenticate
168     the client. The EAP-TLS method will be used if the other eap methods can't
169     be used (no secrets).
170
171     If you're setting up a client, edit the configuration file and then run
172     pppd with 'remotename' option to specify the server name. Add the 
173     'need-peer-eap' option if you want to be sure the peer ask you to
174     authenticate (and to use eap) and to disconnect if it doesn't.
175
176 6. Example
177
178     The following example can be used to connect a Linux client with the 'pptp'
179     package to a Linux server running the 'pptpd' (PoPToP) package. The server
180     was configured with a certificate with name (CN) 'pptp-server', the client
181     was configured with a certificate with name (CN) 'pptp-client', both 
182     signed by the same Certificate Authority (CA).
183
184     Server side:
185       - /etc/pptpd.conf file:
186           option /etc/ppp/options-pptpd-eaptls
187           localip 172.16.1.1
188           remoteip 172.16.1.10-20 
189       - /etc/ppp/options-pptpd-eaptls file:
190           name pptp-server
191           lock 
192           mtu 1500 
193           mru 1450
194           auth 
195           lcp-echo-failure 3 
196           lcp-echo-interval 5 
197           nodeflate 
198           nobsdcomp
199           nopredictor1
200           nopcomp
201           noaccomp
202           
203           require-eap
204           require-mppe-128
205           
206           crl /home/janjust/ppp/keys/crl.pem
207           
208           debug
209           logfile /tmp/pppd.log
210
211       - /etc/ppp/eaptls-server file:
212            * pptp-server - /etc/ppp/pptp-server.crt /etc/ppp/ca.crt /etc/ppp/pptp-server.key *
213
214       - On the server, run 
215           pptdp --conf /etc/pptpd.conf
216        
217     Client side:
218       - Run
219           pppd noauth require-eap require-mppe-128 \
220             ipcp-accept-local ipcp-accept-remote noipdefault \
221             cert  /etc/ppp/keys/pptp-client.crt \
222             key   /etc/ppp/keys/pptp-client.key \
223             ca    /etc/ppp/keys/ca.crt \
224             name pptp-client remotename pptp-server \
225             debug logfile /tmp/pppd.log
226             pty "pptp pptp-server.example.com --nolaunchpppd"
227
228     Check /var/log/messages and the files /tmp/pppd.log on both sides for debugging info.
229
230 7. Notes
231
232     This is experimental code.
233     Send suggestions and comments to Jan Just Keijser <janjust@nikhef.nl>
234