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