From: Alan T. DeKok Date: Mon, 8 Jun 2020 18:31:57 +0000 (-0400) Subject: updated from the old raddb/certs/README X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=e063c24fddce8c1936baf669011d0f6949f6ffc5;p=thirdparty%2Ffreeradius-server.git updated from the old raddb/certs/README --- diff --git a/doc/antora/modules/raddb/pages/certs/README.adoc b/doc/antora/modules/raddb/pages/certs/README.adoc new file mode 100644 index 00000000000..e1845fa3f7a --- /dev/null +++ b/doc/antora/modules/raddb/pages/certs/README.adoc @@ -0,0 +1,224 @@ += Certificates + +This directory contains scripts to create the server certificates. To +make a set of default (i.e. test) certificates, simply type: + +``` +$ ./bootstrap +``` + +The `openssl` command will be run against the sample configuration +files included here, and will make a self-signed certificate authority +(i.e. root CA), and a server certificate. This "root CA" should be +installed on any client machine needing to do EAP-TLS, PEAP, or +EAP-TTLS. + +The Microsoft `XP Extensions` will be automatically included in the +server certificate. Without those extensions Windows clients will refuse +to authenticate to FreeRADIUS. + +The root CA and the `XP Extensions` file also contain a +crlDistributionPoints attribute. The latest release of Windows Phone +needs this to be present for the handset to validate the RADIUS server +certificate. The RADIUS server must have the URI defined but the CA need +not have…however it is best practice for a CA to have a revocation URI. +Note that whilst the Windows Mobile client cannot actually use the CRL +when doing 802.1X it is recommended that the URI be an actual working +URL and contain a revocation format file as there may be other OS +behaviour at play and future OSes that may do something with that URI. + +In general, you should use self-signed certificates for 802.1x (EAP) +authentication. When you list root CAs from other organisations in the +`ca_file`, you permit them to masquerade as you, to authenticate your +users, and to issue client certificates for `EAP-TLS`. + +If FreeRADIUS was configured to use `OpenSSL`, then simply starting the +server in root in debugging mode should also create test certificates, +i.e.: + +``` +$ radiusd -X +``` + +That will cause the `EAP-TLS` module to run the `bootstrap` script in +this directory. The script will be executed only once, the first time +the server has been installed on a particular machine. This bootstrap +script SHOULD be run on installation of any pre-built binary package for +your OS. In any case, the script will ensure that it is not run twice, +and that it does not over-write any existing certificates. + +If you already have CA and server certificates, rename (or delete) this +directory, and create a new `certs` directory containing your +certificates. Note that the `make install` command will NOT over-write +your existing `raddb/certs` directory, which means that the +`bootstrap` command will not be run. + +== New Installations + +We suggest that new installations use the test certificates for initial +tests, and then create real certificates to use for normal user +authentication. See the instructions below for how to create the various +certificates. The old test certificates can be deleted by running the +following command: + +``` +$ rm -f _.pem _.der _.csr _.crt _.key _.p12 serial* index.txt* +``` + +Then, follow the instructions below for creating real certificates. + +Once the final certificates have been created, you can delete the +`bootstrap` command from this directory, and delete the +`make_cert_command` configuration from the `tls` sub-section of +`raddb/mods-available/eap`. + +If you do not want to enable EAP-TLS, PEAP, or EAP-TTLS, then delete the +relevant sub-sections from the `raddb/mods-available/eap` file. + +== Root Certificate + +``` +$ vi ca.cnf +``` + +Edit the `input_password` and `output_password` fields to be the +password for the CA certificate. + +Edit the [certificate_authority] section to have the correct values for +your country, state, etc. + +``` +$ make ca.pem +``` + +This step creates the CA certificate. + +``` +$ make ca.der +``` + +This step creates the DER format of the self-signed certificate, which +is can be imported into Windows. + +== Server Certificate + +The following steps will let you create a server certificate for use +with TLS-based EAP methods, such as EAP-TLS, PEAP, and TTLS. Follow +similar steps to create an "inner-server.pem" file, for use with +EAP-TLS that is tunneled inside of another TLS-based EAP method. + +``` +$ vi server.cnf +``` + +Edit the `input_password` and `output_password` fields to be the +password for the server certificate. + +Edit the [server] section to have the correct values for your country, +state, etc. Be sure that the commonName field here is different from the +commonName for the CA certificate. + +``` +$ make server.pem +``` + +This step creates the server certificate. + +If you have an existing certificate authority, and wish to create a +certificate signing request for the server certificate, edit server.cnf +as above, and type the following command. + +``` +$ make server.csr +``` + +You will have to ensure that the certificate contains the XP extensions +needed by Microsoft clients. + +== Client Certificate + +Client certificates are used by EAP-TLS, and optionally by EAP-TTLS and +PEAP. The following steps outline how to create a client certificate +that is signed by the server certificate created above. You will have to +have the password for the server certificate in the "input_password" +and "output_password" fields of the server.cnf file. + +``` +$ vi client.cnf +``` + +Edit the `input_password` and `output_password` fields to be the +password for the client certificate. You will have to give these +passwords to the end user who will be using the certificates. + +Edit the [client] section to have the correct values for your country, +state, etc. Be sure that the commonName field here is the User-Name that +will be used for logins! + +``` +$ make client.pem +``` + +The users certificate will be in `emailAddress.pem`, i.e. `user@example.com.pem`. + +To create another client certificate, just repeat the steps for making a +client certificate, being sure to enter a different login name for `commonName`, +and a different password. + +== Performance + +EAP performance for EAP-TLS, TTLS, and PEAP is dominated by SSL +calculations. That is, a normal system can handle PAP authentication at +a rate of 10k packets/s. However, SSL involves RSA calculations, which +are very expensive. To benchmark your system, do: + +``` +$ openssl speed rsa +``` + +or + +``` +$ openssl speed rsa2048 +``` + +to test 2048 bit keys. + +That number is also the maximum number of authentications/s that can +be done for `EAP-TLS` (or `TTLS`, or `PEAP`). Typically eh + +== Compatibility + +The certificates created using this method are known to be compatible +with ALL operating systems. Some common issues are: + +* Most systems now require certain OIDs in the certificates. If it doesn’t see + them, it will stop doing EAP. The most visible effect is that the client + starts EAP, gets a few `Access-Challenge` packets, and then a little while + later re-starts EAP. If this happens, see the FAQ, and the comments in + `raddb/mods-available/eap` for how to fix it. + +* Windows requires the root certificates to be on the client PC. If it + doesn’t have them, you will see the same issue as above. + +* Windows XP post SP2 has a bug where it has problems with certificate + chains. i.e. if the server certificate is an intermediate one, and not a + root one, then authentication will silently fail, as above. + +* Some versions of Windows CE cannot handle 4K RSA certificates. They + will (again) silently fail, as above. + +* In none of these cases will Windows give the end user any reasonable + error message describing what went wrong. This leads people to blame the + RADIUS server. That blame is misplaced. + +* Certificate chains of more than 64K bytes are likely to not + work. Most clients cannot handle 64K certificate chains. Most Access + Points will shut down the EAP session after about 50 round trips, + while 64K certificate chains will take about 60 round trips. So + don’t use large certificate chains. They will only work after + everyone upgrade everything in the network. + +* All other operating systems are known to work with EAP and FreeRADIUS. + This includes Linux, *BSD, Mac OS X, Solaris, etc. along with all + known embedded systems, phones, WiFi devices, etc.