src/openvpn/easy-rsa/README

   1 This is a small RSA key management package,
   2 based on the openssl command line tool, that
   3 can be found in the easy-rsa subdirectory
   4 of the OpenVPN distribution.
   5
   6 These are reference notes.  For step
   7 by step instructions, see the HOWTO:
   8
   9 http://openvpn.net/howto.html
  10
  11 INSTALL
  12
  13 1. Edit vars.
  14 2. Set KEY_CONFIG to point to the openssl.cnf file
  15    included in this distribution.
  16 3. Set KEY_DIR to point to a directory which will
  17    contain all keys, certificates, etc.  This
  18    directory need not exist, and if it does,
  19    it will be deleted with rm -rf, so BE
  20    CAREFUL how you set KEY_DIR.
  21 4. (Optional) Edit other fields in vars
  22    per your site data.  You may want to
  23    increase KEY_SIZE to 2048 if you are
  24    paranoid and don't mind slower key
  25    processing, but certainly 1024 is
  26    fine for testing purposes.  KEY_SIZE
  27    must be compatible across both peers
  28    participating in a secure SSL/TLS
  29    connection.
  30 5  . vars
  31 6. ./clean-all
  32 7. As you create certificates, keys, and
  33    certificate signing requests, understand that
  34    only .key files should be kept confidential.
  35    .crt and .csr files can be sent over insecure
  36    channels such as plaintext email.
  37 8. You should never need to copy a .key file
  38    between computers.  Normally each computer
  39    will have its own certificate/key pair.
  40
  41 BUILD YOUR OWN ROOT CERTIFICATE AUTHORITY (CA) CERTIFICATE/KEY
  42
  43 1. ./build-ca
  44 2. ca.crt and ca.key will be built in your KEY_DIR
  45    directory
  46
  47 BUILD AN INTERMEDIATE CERTIFICATE AUTHORITY CERTIFICATE/KEY (optional)
  48
  49 1. ./build-inter inter
  50 2. inter.crt and inter.key will be built in your KEY_DIR
  51    directory and signed with your root certificate.
  52
  53 BUILD DIFFIE-HELLMAN PARAMETERS (necessary for
  54 the server end of a SSL/TLS connection).
  55
  56 1. ./build-dh
  57
  58 BUILD A CERTIFICATE SIGNING REQUEST (If
  59 you want to sign your certificate with a root
  60 certificate controlled by another individual
  61 or organization, or residing on a different machine).
  62
  63 1. Get ca.crt (the root certificate) from your
  64    certificate authority.  Though this
  65    transfer can be over an insecure channel, to prevent
  66    man-in-the-middle attacks you must confirm that
  67    ca.crt was not tampered with.  Large CAs solve this
  68    problem by hardwiring their root certificates into
  69    popular web browsers.  A simple way to verify a root
  70    CA is to call the issuer on the telephone and confirm
  71    that the md5sum or sha1sum signatures on the ca.crt
  72    files match (such as with the command: "md5sum ca.crt").
  73 2. Choose a name for your certificate such as your computer
  74    name.  In our example we will use "mycert".
  75 3. ./build-req mycert
  76 4. You can ignore most of the fields, but set
  77    "Common Name" to something unique such as your
  78    computer's host name.  Leave all password
  79    fields blank, unless you want your private key
  80    to be protected by password.  Using a password
  81    is not required -- it will make your key more secure
  82    but also more inconvenient to use, because you will
  83    need to supply your password anytime the key is used.
  84    NOTE: if you are using a password, use ./build-req-pass
  85    instead of ./build-req
  86 5. Your key will be written to $KEY_DIR/mycert.key
  87 6. Your certificate signing request will be written to
  88    to $KEY_DIR/mycert.csr
  89 7. Email mycert.csr to the individual or organization
  90    which controls the root certificate.  This can be
  91    done over an insecure channel.
  92 8. After the .csr file is signed by the root certificate
  93    authority, you will receive a file mycert.crt
  94    (your certificate).  Place mycert.crt in your
  95    KEY_DIR directory.
  96 9. The combined files of mycert.crt, mycert.key,
  97    and ca.crt can now be used to secure one end of
  98    an SSL/TLS connection.
  99
 100 SIGN A CERTIFICATE SIGNING REQUEST
 101
 102 1. ./sign-req mycert
 103 2. mycert.crt will be built in your KEY_DIR
 104    directory using mycert.csr and your root CA
 105    file as input.
 106
 107 BUILD AND SIGN A CERTIFICATE SIGNING REQUEST
 108 USING A LOCALLY INSTALLED ROOT CERTIFICATE/KEY -- this
 109 script generates and signs a certificate in one step,
 110 but it requires that the generated certificate and private
 111 key files be copied to the destination host over a
 112 secure channel.
 113
 114 1. ./build-key mycert (no password protection)
 115 2. OR ./build-key-pass mycert (with password protection)
 116 3. OR ./build-key-pkcs12 mycert (PKCS #12 format)
 117 4. OR ./build-key-server mycert (with nsCertType=server)
 118 5. mycert.crt and mycert.key will be built in your
 119    KEY_DIR directory, and mycert.crt will be signed
 120    by your root CA. If ./build-key-pkcs12 was used a
 121    mycert.p12 file will also be created including the
 122    private key, certificate and the ca certificate.
 123
 124 IMPORTANT
 125
 126 To avoid a possible Man-in-the-Middle attack where an authorized
 127 client tries to connect to another client by impersonating the
 128 server, make sure to enforce some kind of server certificate
 129 verification by clients.  There are currently four different ways
 130 of accomplishing this, listed in the order of preference:
 131
 132 (1) Build your server certificates with the build-key-server
 133     script.  This will designate the certificate as a
 134     server-only certificate by setting nsCertType=server.
 135     Now add the following line to your client configuration:
 136
 137     ns-cert-type server
 138
 139     This will block clients from connecting to any
 140     server which lacks the nsCertType=server designation
 141     in its certificate, even if the certificate has been
 142     signed by the CA which is cited in the OpenVPN configuration
 143     file (--ca directive).
 144
 145 (2) Use the --tls-remote directive on the client to
 146     accept/reject the server connection based on the common
 147     name of the server certificate.
 148
 149 (3) Use a --tls-verify script or plugin to accept/reject the
 150     server connection based on a custom test of the server
 151     certificate's embedded X509 subject details.
 152
 153 (4) Sign server certificates with one CA and client certificates
 154     with a different CA.  The client config "ca" directive should
 155     reference the server-signing CA while the server config "ca"
 156     directive should reference the client-signing CA.
 157
 158 NOTES
 159
 160 Show certificate fields:
 161   openssl x509 -in cert.crt -text