= 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 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:

```
$ make distclean
```

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
```

This step creates CA certificate using both RSA and ECC keys, in the respective
directories.

```
$ make rsa/ca.der
```

Or:

```
$ make ecc/ca.der
```

These steps create the DER format of the self-signed certificates, 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
```

This step creates and verifies the server certificates using both RSA and ECC
keys.

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 rsa/server.csr
```

Or:

```
$ make ecc/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 CA certificate created above. You will have to
have the password for the CA certificate in the "input_password" and
"output_password" fields of the ca.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
```

The user's certificates (RSA and ECC) will be in `emailAddress.pem` and
`emailAddress.ecc.pem`, e.g. `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.
