File: README.eap-tls

package info (click to toggle)
ppp 2.4.7-2+4.1
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, buster, sid
  • size: 7,100 kB
  • sloc: ansic: 56,241; sh: 1,050; perl: 334; makefile: 114; exp: 82
file content (291 lines) | stat: -rw-r--r-- 11,024 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
EAP-TLS authentication support for PPP
======================================

1. Intro

    The Extensible Authentication Protocol (EAP; RFC 3748) is a
    security protocol that can be used with PPP.  It provides a means
    to plug in multiple optional authentication methods.

    Transport Level Security (TLS; RFC 5216) provides for mutual
    authentication, integrity-protected ciphersuite negotiation and
    key exchange between two endpoints.  It also provides for optional
    MPPE encryption.

    EAP-TLS (RFC 2716) incapsulates the TLS messages in EAP packets,
    allowing TLS mutual authentication to be used as a generic EAP
    mechanism. It also provides optional encryption using the MPPE
    protocol.

    This patch provide EAP-TLS support to pppd.
    This authentication method can be used in both client or server
    mode.

2. Building

    To build pppd with EAP-TLS support, OpenSSL (http://www.openssl.org)
    is required. Any version from 0.9.7 should work.

    Configure, compile, and install as usual.

3. Configuration

    On the client side there are two ways to configure EAP-TLS:

    1. supply the appropriate 'ca', 'cert' and 'key' command-line parameters

    2. edit the /etc/ppp/eaptls-client file.
    Insert a line for each system with which you use EAP-TLS.
    The line is composed of this fields separated by tab:

      - Client name
        The name used by the client for authentication, can be *
      - Server name
        The name of the server, can be *
      - Client certificate file
        The file containing the certificate chain for the
        client in PEM format
      - Server certificate file
        If you want to specify the certificate that the
        server is allowed to use, put the certificate file name.
        Else put a dash '-'.
      - CA certificate file
        The file containing the trusted CA certificates in PEM
        format.
      - Client private key file
        The file containing the client private key in PEM format.


    On the server side edit the /etc/ppp/eaptls-server file.
    Insert a line for each system with which you use EAP-TLS.
    The line is composed of this fields separated by tab:

      - Client name
        The name used by the client for authentication, can be *
      - Server name
        The name of the server, can be *
      - Client certificate file
        If you want to specify the certificate that the
        client is allowed to use, put the certificate file name.
        Else put a dash '-'.
      - Server certificate file
        The file containing the certificate chain for the
        server in PEM format
      - CA certificate file
        The file containing the trusted CA certificates in PEM format.
      - Client private key file
        The file containing the server private key in PEM format.
      - addresses
        A list of IP addresses the client is allowed to use.


    OpenSSL engine support is included starting with v0.95 of this patch.
    Currently the only engine tested is the 'pkcs11' engine (hardware token
    support). To use the 'pksc11' engine:
      - Use a special private key fileiname in the /etc/ppp/eaptls-client file:
          <engine>:<identifier>
        e.g.
          pkcs11:123456

      - The certificate can also be loaded from the 'pkcs11' engine using
        a special client certificate filename in the /etc/ppp/eaptls-client file:
          <engine>:<identifier>
        e.g.
          pkcs11:123456

      - Create an /etc/ppp/openssl.cnf file to load the right OpenSSL engine prior
        to starting 'pppd'. A sample openssl.cnf file is

        openssl_conf = openssl_def

        [ openssl_def ]
        engines = engine_section

        [ engine_section ]
        pkcs11 = pkcs11_section

        [ pkcs11_section ]
        engine_id = pkcs11
        dynamic_path = /usr/lib64/openssl/engines/engine_pkcs11.so
        MODULE_PATH = /usr/lib64/libeTPkcs11.so
        init = 0

      - There are two ways to specify a password/PIN for the PKCS11 engine:
          - inside the openssl.cnf file using
              PIN = your-secret-pin
            Note The keyword 'PIN' is case sensitive!
          - Using the 'password' in the ppp options file.
        From v0.97 of the eap-tls patch the password can also be supplied
        using the appropriate 'eaptls_passwd_hook' (see plugins/passprompt.c
        for an example).


4. Options

    These pppd options are available:

      ca <ca-file>
        Use the CA public certificate found in <ca-file> in PEM format
      cert <cert-file>
        Use the client public certificate found in <cert-file> in PEM format
        or in engine:engine_id format
      key <key-file>
        Use the client private key found in <key-file> in PEM format
        or in engine:engine_id format
      crl <crl-file>
        Use the Certificate Revocation List (CRL) file <crl-file> in PEM format.
      crl-dir <dir>
        Use CRL files from directory <dir>. It contains CRL files in PEM
        format and each file contains a CRL. The files are looked up
        by the issuer name hash value. Use the c_rehash utility
        to create necessary links.
      need-peer-eap
        If the peer doesn't ask us to authenticate or doesn't use eap
        to authenticate us, disconnect.

    Note:
      password-encrypted certificates can be used as of v0.94 of this
      patch. The password for the eap-tls.key file is specified using
      the regular
          password ....
      statement in the ppp options file, or by using the appropriate
      plugin which supplies a 'eaptls_passwd_hook' routine.

5. Connecting

    If you're setting up a pppd server, edit the EAP-TLS configuration file
    as written above and then run pppd with the 'auth' option to authenticate
    the client. The EAP-TLS method will be used if the other eap methods can't
    be used (no secrets).

    If you're setting up a client, edit the configuration file and then run
    pppd with 'remotename' option to specify the server name. Add the
    'need-peer-eap' option if you want to be sure the peer ask you to
    authenticate (and to use eap) and to disconnect if it doesn't.

6. Example

    The following example can be used to connect a Linux client with the 'pptp'
    package to a Linux server running the 'pptpd' (PoPToP) package. The server
    was configured with a certificate with name (CN) 'pptp-server', the client
    was configured with a certificate with name (CN) 'pptp-client', both
    signed by the same Certificate Authority (CA).

    Server side:
      - /etc/pptpd.conf file:
          option /etc/ppp/options-pptpd-eaptls
          localip 172.16.1.1
          remoteip 172.16.1.10-20
      - /etc/ppp/options-pptpd-eaptls file:
          name pptp-server
          lock
          mtu 1500
          mru 1450
          auth
          lcp-echo-failure 3
          lcp-echo-interval 5
          nodeflate
          nobsdcomp
          nopredictor1
          nopcomp
          noaccomp

          require-eap
          require-mppe-128

          crl /home/janjust/ppp/keys/crl.pem

          debug
          logfile /tmp/pppd.log

      - /etc/ppp/eaptls-server file:
           * pptp-server - /etc/ppp/pptp-server.crt /etc/ppp/ca.crt /etc/ppp/pptp-server.key *

      - On the server, run
          pptdp --conf /etc/pptpd.conf

    Client side:
      - Run
          pppd noauth require-eap require-mppe-128 \
            ipcp-accept-local ipcp-accept-remote noipdefault \
            cert  /etc/ppp/keys/pptp-client.crt \
            key   /etc/ppp/keys/pptp-client.key \
            ca    /etc/ppp/keys/ca.crt \
            name pptp-client remotename pptp-server \
            debug logfile /tmp/pppd.log
            pty "pptp pptp-server.example.com --nolaunchpppd"

    Check /var/log/messages and the files /tmp/pppd.log on both sides for debugging info.

7. Notes

    This is experimental code.
    Send suggestions and comments to Jan Just Keijser <janjust@nikhef.nl>

8. Changelog of ppp-<>-eaptls-mppe-* patches

v0.7     (22-Nov-2005)
 - First version of the patch to include MPPE support
 - ppp-2.4.3 only
v0.9     (25-Jul-2006)
 - Bug fixes
 - First version for ppp-2.4.4
v0.91    (03-Sep-2006)
 - Added missing #include for md5.h
 - Last version for ppp-2.4.3
v0.92    (22-Apr-2008)
 - Fix for openssl 0.9.8 issue with md5 function overload.
v0.93    (14-Aug-2008)
 - Make sure 'noauth' option can be used to bypass server certificate verification.
v0.94    (15-Oct-2008)
 - Added support for password-protected private keys by (ab)using the 'password' field.
v0.95    (23-Dec-2009)
 - First version with OpenSSL engine support.
v0.96    (27-Jan-2010)
 - Added fully functional support for OpenSSL engines (PKCS#11)
 - First version for ppp-2.4.5
v0.97    (20-Apr-2010)
 - Some bug fixes for v0.96
 - Added support for entering the password via a plugin. The sample plugin
     .../pppd/plugins/passprompt.c has been extended with EAP-TLS support.
   The "old" methods using the password option or the /etc/ppp/openssl.cnf file still work.
 - Added support for specifying the client CA, certificate and private key on the command-line
   or via the ppp config file.
v0.98    (20-Apr-2010)
 - Fix initialisation bug when using ca/cert/key command-line options.
 - Last version for ppp-2.4.4
v0.99    (05-Oct-2010)
 - Fix coredump when using multilink option.
v0.991   (08-Aug-2011)
 - Fix compilation issue with openssl 1.0.
v0.992   (01-Dec-2011)
 - Fix compilation issue with eaptls_check_hook and passwordfd plugin.
v0.993   (24-Apr-2012)
 - Fix compilation issue when EAP_TLS=n in pppd/Makefile.
v0.994   (11-Jun-2012)
 - Fix compilation issue on Ubuntu 11.10.
v0.995   (27-May-2014)
 - Add support for a CRL file using the command-line option 'crl'
   (prior only 'crl-dir' was supported).
 - Fix segfault when pkcs11 enginename was not specified correctly.
 - Fix segfault when client was misconfigured.
 - Disable SSL Session Ticket support as Windows 8 does not support this.
v0.996   (28-May-2014)
 - Fix minor bug where SessionTicket message was printed as 'Unknown SSL3 code 4'
 - Add EAP-TLS-specific options to pppd.8 manual page.
 - Updated README.eap-tls file with new options and provide an example.
v0.997   (19-Jun-2014)
 - Change SSL_OP_NO_TICKETS to SSL_OP_NO_TICKET
 - Fix bug in initialisation code with fragmented packets.
v0.998   (13-Mar-2015)
 - Add fix for https://bugzilla.redhat.com/show_bug.cgi?id=1023620
v0.999   (11-May-2017)
 - Add support for OpenSSL 1.1: the code will now compile against OpenSSL 1.0.x or 1.1.x.
v1.101 (1-Jun-2018)
 - Fix vulnerabilities CVE-2018-11574.
v1.102 (2-Nov-2018)
 - Add TLS 1.2 support. Windows 7/8 will connect using TLS 1.0, Windows 10 clients using TLS 1.2.
   This works both when compiling against OpenSSL 1.0.1+ and 1.1+.
 - Print warning when certificate is either not yet valid or has expired.
 - Perform better peer certificate checks.
 - Allow certificate chain files to be used.