1EAP-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    EAP-TLS support is included in pppd, and is enabled or disabled
21    at configure time by using the --enable-eaptls and --disable-eaptls
22    arguments to ./configure.
23
24    This authentication method can be used in both client and server mode.
25
262. Building
27
28    To build pppd with EAP-TLS support, OpenSSL (http://www.openssl.org)
29    is required. Any version from 0.9.7 should work.
30
31    Configure, compile, and install as usual.
32
333. Configuration
34
35    On the client side there are two ways to configure EAP-TLS:
36
37    1. supply the appropriate 'ca', 'cert' and 'key' command-line parameters
38
39    2. edit the /etc/ppp/eaptls-client file.
40    Insert a line for each system with which you use EAP-TLS.
41    The line is composed of this fields separated by tab:
42
43      - Client name
44        The name used by the client for authentication, can be *
45      - Server name
46        The name of the server, can be *
47      - Client certificate file
48        The file containing the certificate chain for the
49        client in PEM format
50      - Server certificate file
51        If you want to specify the certificate that the
52        server is allowed to use, put the certificate file name.
53        Else put a dash '-'.
54      - CA certificate file
55        The file containing the trusted CA certificates in PEM
56        format.
57      - Client private key file
58        The file containing the client private key in PEM format.
59
60
61    On the server side edit the /etc/ppp/eaptls-server file.
62    Insert a line for each system with which you use EAP-TLS.
63    The line is composed of this fields separated by tab:
64
65      - Client name
66        The name used by the client for authentication, can be *
67      - Server name
68        The name of the server, can be *
69      - Client certificate file
70        If you want to specify the certificate that the
71        client is allowed to use, put the certificate file name.
72        Else put a dash '-'.
73      - Server certificate file
74        The file containing the certificate chain for the
75        server in PEM format
76      - CA certificate file
77        The file containing the trusted CA certificates in PEM format.
78      - Client private key file
79        The file containing the server private key in PEM format.
80      - addresses
81        A list of IP addresses the client is allowed to use.
82
83
84    OpenSSL engine support is included starting with v0.95 of this patch.
85    Currently the only engine tested is the 'pkcs11' engine (hardware token
86    support). To use the 'pksc11' engine:
87      - Use a special private key fileiname in the /etc/ppp/eaptls-client file:
88          <engine>:<identifier>
89        e.g.
90          pkcs11:123456
91
92      - The certificate can also be loaded from the 'pkcs11' engine using
93        a special client certificate filename in the /etc/ppp/eaptls-client file:
94          <engine>:<identifier>
95        e.g.
96          pkcs11:123456
97
98      - Create an /etc/ppp/openssl.cnf file to load the right OpenSSL engine prior
99        to starting 'pppd'. A sample openssl.cnf file is
100
101        openssl_conf = openssl_def
102
103        [ openssl_def ]
104        engines = engine_section
105
106        [ engine_section ]
107        pkcs11 = pkcs11_section
108
109        [ pkcs11_section ]
110        engine_id = pkcs11
111        dynamic_path = /usr/lib64/openssl/engines/engine_pkcs11.so
112        MODULE_PATH = /usr/lib64/libeTPkcs11.so
113        init = 0
114
115      - There are two ways to specify a password/PIN for the PKCS11 engine:
116          - inside the openssl.cnf file using
117              PIN = your-secret-pin
118            Note The keyword 'PIN' is case sensitive!
119          - Using the 'password' in the ppp options file.
120        From v0.97 of the eap-tls patch the password can also be supplied
121        using the appropriate 'eaptls_passwd_hook' (see plugins/passprompt.c
122        for an example).
123
124
1254. Options
126
127    These pppd options are available:
128
129      ca <ca-file>
130        Use the CA public certificate found in <ca-file> in PEM format
131      capath <directory>
132        Use the directory <directory> as the CA public certificate directory
133      cert <cert-file>
134        Use the client public certificate found in <cert-file> in PEM format
135        or in engine:engine_id format
136      key <key-file>
137        Use the client private key found in <key-file> in PEM format
138        or in engine:engine_id format
139      pkcs12 <pkcs12-file>
140        Use a pkcs12 envelope as a substitute for cert and key. A password may be
141        required to use this file.
142      crl <crl-file>
143        Use the Certificate Revocation List (CRL) file <crl-file> in PEM format.
144      crl-dir <dir>
145        Use CRL files from directory <dir>. It contains CRL files in PEM
146        format and each file contains a CRL. The files are looked up
147        by the issuer name hash value. Use the c_rehash utility
148        to create necessary links.
149      need-peer-eap
150        If the peer doesn't ask us to authenticate or doesn't use eap
151        to authenticate us, disconnect.
152      max-tls-version <1.0|1.1|1.2 (default)|1.3>
153        Specify the maximum TLS protocol version to negotiate with peers. Defaults
154        to TLSv1.2 as the TLSv1.3 code is experimental.
155      tls-verify-key-usage
156        Validate certificate purpose and extended key usage
157      tls-verify-method <none|subject|name|suffix>
158        Compare the remotename against the subject, certificate name, or
159        match by suffix. Default is 'name'.
160
161    Note:
162      password-encrypted certificates can be used as of v0.94 of this
163      patch. The password for the eap-tls.key file is specified using
164      the regular
165          password ....
166      statement in the ppp options file, or by using the appropriate
167      plugin which supplies a 'eaptls_passwd_hook' routine.
168
1695. Connecting
170
171    If you're setting up a pppd server, edit the EAP-TLS configuration file
172    as written above and then run pppd with the 'auth' option to authenticate
173    the client. The EAP-TLS method will be used if the other eap methods can't
174    be used (no secrets).
175
176    If you're setting up a client, edit the configuration file and then run
177    pppd with 'remotename' option to specify the server name. Add the
178    'need-peer-eap' option if you want to be sure the peer ask you to
179    authenticate (and to use eap) and to disconnect if it doesn't.
180
1816. Example
182
183    The following example can be used to connect a Linux client with the 'pptp'
184    package to a Linux server running the 'pptpd' (PoPToP) package. The server
185    was configured with a certificate with name (CN) 'pptp-server', the client
186    was configured with a certificate with name (CN) 'pptp-client', both
187    signed by the same Certificate Authority (CA).
188
189    Server side:
190      - /etc/pptpd.conf file:
191          option /etc/ppp/options-pptpd-eaptls
192          localip 172.16.1.1
193          remoteip 172.16.1.10-20
194      - /etc/ppp/options-pptpd-eaptls file:
195          name pptp-server
196          lock
197          mtu 1500
198          mru 1450
199          auth
200          lcp-echo-failure 3
201          lcp-echo-interval 5
202          nodeflate
203          nobsdcomp
204          nopredictor1
205          nopcomp
206          noaccomp
207
208          require-eap
209          require-mppe-128
210
211          crl /home/janjust/ppp/keys/crl.pem
212
213          debug
214          logfile /tmp/pppd.log
215
216      - /etc/ppp/eaptls-server file:
217           * pptp-server - /etc/ppp/pptp-server.crt /etc/ppp/ca.crt /etc/ppp/pptp-server.key *
218
219      - On the server, run
220          pptdp --conf /etc/pptpd.conf
221
222    Client side:
223      - Run
224          pppd noauth require-eap require-mppe-128 \
225            ipcp-accept-local ipcp-accept-remote noipdefault \
226            cert  /etc/ppp/keys/pptp-client.crt \
227            key   /etc/ppp/keys/pptp-client.key \
228            ca    /etc/ppp/keys/ca.crt \
229            name pptp-client remotename pptp-server \
230            debug logfile /tmp/pppd.log
231            pty "pptp pptp-server.example.com --nolaunchpppd"
232
233    Check /var/log/messages and the files /tmp/pppd.log on both sides for debugging info.
234
2357. Notes
236
237    This is experimental code.
238    Send suggestions and comments to Jan Just Keijser <janjust@nikhef.nl>
239
240