A R Karthick | 307483c | 2016-06-06 17:05:19 -0700 | [diff] [blame] | 1 | This directory contains scripts to create the server certificates. |
| 2 | To make a set of default (i.e. test) certificates, simply type: |
| 3 | |
| 4 | $ ./bootstrap |
| 5 | |
| 6 | The "openssl" command will be run against the sample configuration |
| 7 | files included here, and will make a self-signed certificate authority |
| 8 | (i.e. root CA), and a server certificate. This "root CA" should be |
| 9 | installed on any client machine needing to do EAP-TLS, PEAP, or |
| 10 | EAP-TTLS. |
| 11 | |
| 12 | The Microsoft "XP Extensions" will be automatically included in the |
| 13 | server certificate. Without those extensions Windows clients will |
| 14 | refuse to authenticate to FreeRADIUS. |
| 15 | |
| 16 | The root CA and the "XP Extensions" file also contain a crlDistributionPoints |
| 17 | attribute. The latest release of Windows Phone needs this to be present |
| 18 | for the handset to validate the RADIUS server certificate. The RADIUS |
| 19 | server must have the URI defined but the CA need not have...however it |
| 20 | is best practice for a CA to have a revocation URI. Note that whilst |
| 21 | the Windows Mobile client cannot actually use the CRL when doing 802.1X |
| 22 | it is recommended that the URI be an actual working URL and contain a |
| 23 | revocation format file as there may be other OS behaviour at play and |
| 24 | future OSes that may do something with that URI. |
| 25 | |
| 26 | In general, you should use self-signed certificates for 802.1x (EAP) |
| 27 | authentication. When you list root CAs from other organisations in |
| 28 | the "ca_file", you permit them to masquerade as you, to authenticate |
| 29 | your users, and to issue client certificates for EAP-TLS. |
| 30 | |
| 31 | If FreeRADIUS was configured to use OpenSSL, then simply starting |
| 32 | the server in root in debugging mode should also create test |
| 33 | certificates, i.e.: |
| 34 | |
| 35 | $ radiusd -X |
| 36 | |
| 37 | That will cause the EAP-TLS module to run the "bootstrap" script in |
| 38 | this directory. The script will be executed only once, the first time |
| 39 | the server has been installed on a particular machine. This bootstrap |
| 40 | script SHOULD be run on installation of any pre-built binary package |
| 41 | for your OS. In any case, the script will ensure that it is not run |
| 42 | twice, and that it does not over-write any existing certificates. |
| 43 | |
| 44 | If you already have CA and server certificates, rename (or delete) |
| 45 | this directory, and create a new "certs" directory containing your |
| 46 | certificates. Note that the "make install" command will NOT |
| 47 | over-write your existing "raddb/certs" directory, which means that the |
| 48 | "bootstrap" command will not be run. |
| 49 | |
| 50 | |
| 51 | NEW INSTALLATIONS OF FREERADIUS |
| 52 | |
| 53 | |
| 54 | We suggest that new installations use the test certificates for |
| 55 | initial tests, and then create real certificates to use for normal |
| 56 | user authentication. See the instructions below for how to create the |
| 57 | various certificates. The old test certificates can be deleted by |
| 58 | running the following command: |
| 59 | |
| 60 | $ rm -f *.pem *.der *.csr *.crt *.key *.p12 serial* index.txt* |
| 61 | |
| 62 | Then, follow the instructions below for creating real certificates. |
| 63 | |
| 64 | Once the final certificates have been created, you can delete the |
| 65 | "bootstrap" command from this directory, and delete the |
| 66 | "make_cert_command" configuration from the "tls" sub-section of |
| 67 | eap.conf. |
| 68 | |
| 69 | If you do not want to enable EAP-TLS, PEAP, or EAP-TTLS, then delete |
| 70 | the relevant sub-sections from the "eap.conf" file. |
| 71 | |
| 72 | |
| 73 | MAKING A ROOT CERTIFICATE |
| 74 | |
| 75 | |
| 76 | $ vi ca.cnf |
| 77 | |
| 78 | Edit the "input_password" and "output_password" fields to be the |
| 79 | password for the CA certificate. |
| 80 | |
| 81 | Edit the [certificate_authority] section to have the correct values |
| 82 | for your country, state, etc. |
| 83 | |
| 84 | $ make ca.pem |
| 85 | |
| 86 | This step creates the CA certificate. |
| 87 | |
| 88 | $ make ca.der |
| 89 | |
| 90 | This step creates the DER format of the self-signed certificate, |
| 91 | which is can be imported into Windows. |
| 92 | |
| 93 | |
| 94 | MAKING A SERVER CERTIFICATE |
| 95 | |
| 96 | |
| 97 | $ vi server.cnf |
| 98 | |
| 99 | Edit the "input_password" and "output_password" fields to be the |
| 100 | password for the server certificate. |
| 101 | |
| 102 | Edit the [server] section to have the correct values for your |
| 103 | country, state, etc. Be sure that the commonName field here is |
| 104 | different from the commonName for the CA certificate. |
| 105 | |
| 106 | $ make server.pem |
| 107 | |
| 108 | This step creates the server certificate. |
| 109 | |
| 110 | If you have an existing certificate authority, and wish to create a |
| 111 | certificate signing request for the server certificate, edit |
| 112 | server.cnf as above, and type the following command. |
| 113 | |
| 114 | $ make server.csr |
| 115 | |
| 116 | You will have to ensure that the certificate contains the XP |
| 117 | extensions needed by Microsoft clients. |
| 118 | |
| 119 | |
| 120 | MAKING A CLIENT CERTIFICATE |
| 121 | |
| 122 | |
| 123 | Client certificates are used by EAP-TLS, and optionally by EAP-TTLS |
| 124 | and PEAP. The following steps outline how to create a client |
| 125 | certificate that is signed by the server certificate created above. |
| 126 | You will have to have the password for the server certificate in the |
| 127 | "input_password" and "output_password" fields of the server.cnf file. |
| 128 | |
| 129 | |
| 130 | $ vi client.cnf |
| 131 | |
| 132 | Edit the "input_password" and "output_password" fields to be the |
| 133 | password for the client certificate. You will have to give these |
| 134 | passwords to the end user who will be using the certificates. |
| 135 | |
| 136 | Edit the [client] section to have the correct values for your |
| 137 | country, state, etc. Be sure that the commonName field here is |
| 138 | the User-Name that will be used for logins! |
| 139 | |
| 140 | $ make client.pem |
| 141 | |
| 142 | The users certificate will be in "emailAddress.pem", |
| 143 | i.e. "user@example.com.pem". |
| 144 | |
| 145 | To create another client certificate, just repeat the steps for |
| 146 | making a client certificate, being sure to enter a different login |
| 147 | name for "commonName", and a different password. |
| 148 | |
| 149 | |
| 150 | PERFORMANCE |
| 151 | |
| 152 | |
| 153 | EAP performance for EAP-TLS, TTLS, and PEAP is dominated by SSL |
| 154 | calculations. That is, a normal system can handle PAP |
| 155 | authentication at a rate of 10k packets/s. However, SSL involves |
| 156 | RSA calculations, which are very expensive. To benchmark your system, |
| 157 | do: |
| 158 | |
| 159 | $ openssl speed rsa |
| 160 | |
| 161 | or |
| 162 | |
| 163 | $ openssl speed rsa2048 |
| 164 | |
| 165 | to test 2048 bit keys. |
| 166 | |
| 167 | A 1GHz system will likely do 30 calculations/s. A 2GHz system may |
| 168 | do 50 calculations/s, or more. That number is also the number of |
| 169 | authentications/s that can be done for EAP-TLS (or TTLS, or PEAP). |
| 170 | |
| 171 | |
| 172 | COMPATIBILITY |
| 173 | |
| 174 | The certificates created using this method are known to be compatible |
| 175 | with ALL operating systems. Some common issues are: |
| 176 | |
| 177 | - Windows requires certain OIDs in the certificates. If it doesn't |
| 178 | see them, it will stop doing EAP. The most visible effect is |
| 179 | that the client starts EAP, gets a few Access-Challenge packets, |
| 180 | and then a little while later re-starts EAP. If this happens, see |
| 181 | the FAQ, and the comments in raddb/eap.conf for how to fix it. |
| 182 | |
| 183 | - Windows requires the root certificates to be on the client PC. |
| 184 | If it doesn't have them, you will see the same issue as above. |
| 185 | |
| 186 | - Windows XP post SP2 has a bug where it has problems with |
| 187 | certificate chains. i.e. if the server certificate is an |
| 188 | intermediate one, and not a root one, then authentication will |
| 189 | silently fail, as above. |
| 190 | |
| 191 | - Some versions of Windows CE cannot handle 4K RSA certificates. |
| 192 | They will (again) silently fail, as above. |
| 193 | |
| 194 | - In none of these cases will Windows give the end user any |
| 195 | reasonable error message describing what went wrong. This leads |
| 196 | people to blame the RADIUS server. That blame is misplaced. |
| 197 | |
| 198 | - Certificate chains of more than 64K bytes are known to not work. |
| 199 | This is a problem in FreeRADIUS. However, most clients cannot |
| 200 | handle 64K certificate chains. Most Access Points will shut down |
| 201 | the EAP session after about 50 round trips, while 64K certificate |
| 202 | chains will take about 60 round trips. So don't use large |
| 203 | certificate chains. They will only work after everyone upgrade |
| 204 | everything in the network. |
| 205 | |
| 206 | - All other operating systems are known to work with EAP and |
| 207 | FreeRADIUS. This includes Linux, *BSD, Mac OS X, Solaris, |
| 208 | Symbian, along with all known embedded systems, phones, WiFi |
| 209 | devices, etc. |
| 210 | |
| 211 | - Someone needs to ask Microsoft to please stop making life hard for |
| 212 | their customers. |
| 213 | |
| 214 | |
| 215 | SECURITY CONSIDERATIONS |
| 216 | |
| 217 | The default certificate configuration files uses MD5 for message |
| 218 | digests, to maintain compatibility with network equipment that |
| 219 | supports only this algorithm. |
| 220 | |
| 221 | MD5 has known weaknesses and is discouraged in favour of SHA1 (see |
| 222 | http://www.kb.cert.org/vuls/id/836068 for details). If your network |
| 223 | equipment supports the SHA1 signature algorithm, we recommend that you |
| 224 | change the "ca.cnf", "server.cnf", and "client.cnf" files to specify |
| 225 | the use of SHA1 for the certificates. To do this, change the |
| 226 | 'default_md' entry in those files from 'md5' to 'sha1'. |