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 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 26 2. 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 33 3. 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 125 4. 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 169 5. 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 181 6. 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 235 7. Notes 236 237 This is experimental code. 238 Send suggestions and comments to Jan Just Keijser <janjust (a] nikhef.nl> 239 240
Indexes created Wed May 06 00:24:28 UTC 2026