raddb/certs/README

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