xf.li | 8402749 | 2024-04-09 00:17:51 -0700 | [diff] [blame^] | 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 | pkcs12 <pkcs12-file> |
| 138 | Use a pkcs12 envelope as a substitute for cert and key. A password may be |
| 139 | required to use this file. |
| 140 | crl <crl-file> |
| 141 | Use the Certificate Revocation List (CRL) file <crl-file> in PEM format. |
| 142 | crl-dir <dir> |
| 143 | Use CRL files from directory <dir>. It contains CRL files in PEM |
| 144 | format and each file contains a CRL. The files are looked up |
| 145 | by the issuer name hash value. Use the c_rehash utility |
| 146 | to create necessary links. |
| 147 | need-peer-eap |
| 148 | If the peer doesn't ask us to authenticate or doesn't use eap |
| 149 | to authenticate us, disconnect. |
| 150 | max-tls-version <1.0|1.1|1.2 (default)|1.3> |
| 151 | Specify the maximum TLS protocol version to negotiate with peers. Defaults |
| 152 | to TLSv1.2 as the TLSv1.3 code is experimental. |
| 153 | tls-verify-key-usage |
| 154 | Validate certificate purpose and extended key usage |
| 155 | tls-verify-method <none|subject|name|suffix> |
| 156 | Compare the remotename against the subject, certificate name, or |
| 157 | match by suffix. Default is 'name'. |
| 158 | |
| 159 | Note: |
| 160 | password-encrypted certificates can be used as of v0.94 of this |
| 161 | patch. The password for the eap-tls.key file is specified using |
| 162 | the regular |
| 163 | password .... |
| 164 | statement in the ppp options file, or by using the appropriate |
| 165 | plugin which supplies a 'eaptls_passwd_hook' routine. |
| 166 | |
| 167 | 5. Connecting |
| 168 | |
| 169 | If you're setting up a pppd server, edit the EAP-TLS configuration file |
| 170 | as written above and then run pppd with the 'auth' option to authenticate |
| 171 | the client. The EAP-TLS method will be used if the other eap methods can't |
| 172 | be used (no secrets). |
| 173 | |
| 174 | If you're setting up a client, edit the configuration file and then run |
| 175 | pppd with 'remotename' option to specify the server name. Add the |
| 176 | 'need-peer-eap' option if you want to be sure the peer ask you to |
| 177 | authenticate (and to use eap) and to disconnect if it doesn't. |
| 178 | |
| 179 | 6. Example |
| 180 | |
| 181 | The following example can be used to connect a Linux client with the 'pptp' |
| 182 | package to a Linux server running the 'pptpd' (PoPToP) package. The server |
| 183 | was configured with a certificate with name (CN) 'pptp-server', the client |
| 184 | was configured with a certificate with name (CN) 'pptp-client', both |
| 185 | signed by the same Certificate Authority (CA). |
| 186 | |
| 187 | Server side: |
| 188 | - /etc/pptpd.conf file: |
| 189 | option /etc/ppp/options-pptpd-eaptls |
| 190 | localip 172.16.1.1 |
| 191 | remoteip 172.16.1.10-20 |
| 192 | - /etc/ppp/options-pptpd-eaptls file: |
| 193 | name pptp-server |
| 194 | lock |
| 195 | mtu 1500 |
| 196 | mru 1450 |
| 197 | auth |
| 198 | lcp-echo-failure 3 |
| 199 | lcp-echo-interval 5 |
| 200 | nodeflate |
| 201 | nobsdcomp |
| 202 | nopredictor1 |
| 203 | nopcomp |
| 204 | noaccomp |
| 205 | |
| 206 | require-eap |
| 207 | require-mppe-128 |
| 208 | |
| 209 | crl /home/janjust/ppp/keys/crl.pem |
| 210 | |
| 211 | debug |
| 212 | logfile /tmp/pppd.log |
| 213 | |
| 214 | - /etc/ppp/eaptls-server file: |
| 215 | * pptp-server - /etc/ppp/pptp-server.crt /etc/ppp/ca.crt /etc/ppp/pptp-server.key * |
| 216 | |
| 217 | - On the server, run |
| 218 | pptdp --conf /etc/pptpd.conf |
| 219 | |
| 220 | Client side: |
| 221 | - Run |
| 222 | pppd noauth require-eap require-mppe-128 \ |
| 223 | ipcp-accept-local ipcp-accept-remote noipdefault \ |
| 224 | cert /etc/ppp/keys/pptp-client.crt \ |
| 225 | key /etc/ppp/keys/pptp-client.key \ |
| 226 | ca /etc/ppp/keys/ca.crt \ |
| 227 | name pptp-client remotename pptp-server \ |
| 228 | debug logfile /tmp/pppd.log |
| 229 | pty "pptp pptp-server.example.com --nolaunchpppd" |
| 230 | |
| 231 | Check /var/log/messages and the files /tmp/pppd.log on both sides for debugging info. |
| 232 | |
| 233 | 7. Notes |
| 234 | |
| 235 | This is experimental code. |
| 236 | Send suggestions and comments to Jan Just Keijser <janjust@nikhef.nl> |
| 237 | |