src/openvpn/easy-rsa/2.0/README

   1 EASY-RSA Version 2.0-rc1
   2
   3 This is a small RSA key management package, based on the openssl
   4 command line tool, that can be found in the easy-rsa subdirectory
   5 of the OpenVPN distribution.
   6
   7 These are reference notes.  For step-by-step instructions, see the
   8 HOWTO:
   9
  10 http://openvpn.net/howto.html
  11
  12 This package is based on the ./pkitool script.  Run ./pkitool
  13 without arguments for a detailed help message (which is also pasted
  14 below).
  15
  16 Release Notes for easy-rsa-2.0
  17
  18 * Most functionality has been consolidated into the pkitool
  19   script. For compatibility, all previous scripts from 1.0 such
  20   as build-key and build-key-server are provided as stubs
  21   which call pkitool to do the real work.
  22
  23 * pkitool has a --batch flag (enabled by default) which generates
  24   keys/certs without needing any interactive input.  pkitool
  25   can still generate certs/keys using interactive prompting by
  26   using the --interact flag.
  27
  28 * The inherit-inter script has been provided for creating
  29   a new PKI rooted on an intermediate certificate built within a
  30   higher-level PKI.  See comments in the inherit-inter script
  31   for more info.
  32
  33 * The openssl.cnf file has been modified.  pkitool will not
  34   work with the openssl.cnf file included with previous
  35   easy-rsa releases.
  36
  37 * The vars file has been modified -- the following extra
  38   variables have been added: EASY_RSA, CA_EXPIRE,
  39   KEY_EXPIRE.
  40
  41 * The make-crl and revoke-crt scripts have been removed and
  42   are replaced by the revoke-full script.
  43
  44 * The "Organizational Unit" X509 field can be set using
  45   the KEY_OU environmental variable before calling pkitool.
  46
  47 * This release only affects the Linux/Unix version of easy-rsa.
  48   The Windows version (written to use the Windows shell) is unchanged.
  49
  50 * Use the revoke-full script to revoke a certificate, and generate
  51   (or update) the crl.pem file in the keys directory (as set by the
  52   vars script).  Then use "crl-verify crl.pem" in your OpenVPN server
  53   config file, so that OpenVPN can reject any connections coming from
  54   clients which present a revoked certificate.  Usage for the script is:
  55
  56     revoke-full <common-name>
  57
  58   Note this this procedure is primarily designed to revoke client
  59   certificates. You could theoretically use this method to revoke
  60   server certificates as well, but then you would need to propagate
  61   the crl.pem file to all clients as well, and have them include
  62   "crl-verify crl.pem" in their configuration files.
  63
  64 * PKCS#11 support was added.
  65
  66 INSTALL easy-rsa
  67
  68 1. Edit vars.
  69 2. Set KEY_CONFIG to point to the openssl.cnf file
  70    included in this distribution.
  71 3. Set KEY_DIR to point to a directory which will
  72    contain all keys, certificates, etc.  This
  73    directory need not exist, and if it does,
  74    it will be deleted with rm -rf, so BE
  75    CAREFUL how you set KEY_DIR.
  76 4. (Optional) Edit other fields in vars
  77    per your site data.  You may want to
  78    increase KEY_SIZE to 2048 if you are
  79    paranoid and don't mind slower key
  80    processing, but certainly 1024 is
  81    fine for testing purposes.  KEY_SIZE
  82    must be compatible across both peers
  83    participating in a secure SSL/TLS
  84    connection.
  85 5. (Optional) If you intend to use PKCS#11,
  86    install openssl >= 0.9.7, install the
  87    following components from www.opensc.org:
  88    - opensc >= 0.10.0
  89    - engine_pkcs11 >= 0.1.3
  90    Update the openssl.cnf to load the engine:
  91    - Uncomment pkcs11 under engine_section.
  92    - Validate path at dynamic_path under pkcs11_section.
  93 6. . vars
  94 7. ./clean-all
  95 8. As you create certificates, keys, and
  96    certificate signing requests, understand that
  97    only .key files should be kept confidential.
  98    .crt and .csr files can be sent over insecure
  99    channels such as plaintext email.
 100
 101 IMPORTANT
 102
 103 To avoid a possible Man-in-the-Middle attack where an authorized
 104 client tries to connect to another client by impersonating the
 105 server, make sure to enforce some kind of server certificate
 106 verification by clients.  There are currently four different ways
 107 of accomplishing this, listed in the order of preference:
 108
 109 (1) Build your server certificates with specific key usage and
 110     extended key usage. The RFC3280 determine that the following
 111     attributes should be provided for TLS connections:
 112
 113     Mode      Key usage                          Extended key usage
 114     ---------------------------------------------------------------------------
 115     Client    digitalSignature                   TLS Web Client Authentication
 116               keyAgreement
 117               digitalSignature, keyAgreement
 118
 119     Server    digitalSignature, keyEncipherment  TLS Web Server Authentication
 120               digitalSignature, keyAgreement
 121
 122     Now add the following line to your client configuration:
 123
 124     remote-cert-tls server
 125
 126     This will block clients from connecting to any
 127     server which lacks the required extension designation
 128     in its certificate, even if the certificate has been
 129     signed by the CA which is cited in the OpenVPN configuration
 130     file (--ca directive).
 131
 132 (3) Use the --tls-remote directive on the client to
 133     accept/reject the server connection based on the common
 134     name of the server certificate.
 135
 136 (3) Use a --tls-verify script or plugin to accept/reject the
 137     server connection based on a custom test of the server
 138     certificate's embedded X509 subject details.
 139
 140 (4) Sign server certificates with one CA and client certificates
 141     with a different CA.  The client config "ca" directive should
 142     reference the server-signing CA while the server config "ca"
 143     directive should reference the client-signing CA.
 144
 145 NOTES
 146
 147 Show certificate fields:
 148   openssl x509 -in cert.crt -text
 149
 150 PKITOOL documentation
 151
 152 pkitool 2.0
 153 Usage: pkitool [options...] [common-name]
 154 Options:
 155   --batch    : batch mode (default)
 156   --keysize  : Set keysize
 157       size   : size (default=1024)
 158   --interact : interactive mode
 159   --server   : build server cert
 160   --initca   : build root CA
 161   --inter    : build intermediate CA
 162   --pass     : encrypt private key with password
 163   --csr      : only generate a CSR, do not sign
 164   --sign     : sign an existing CSR
 165   --pkcs12   : generate a combined PKCS#12 file
 166   --pkcs11   : generate certificate on PKCS#11 token
 167       lib    : PKCS#11 library
 168       slot   : PKCS#11 slot
 169       id     : PKCS#11 object id (hex string)
 170       label  : PKCS#11 object label
 171 Standalone options:
 172   --pkcs11-slots   : list PKCS#11 slots
 173       lib    : PKCS#11 library
 174   --pkcs11-objects : list PKCS#11 token objects
 175       lib    : PKCS#11 library
 176       slot   : PKCS#11 slot
 177   --pkcs11-init    : initialize PKCS#11 token DANGEROUS!!!
 178       lib    : PKCS#11 library
 179       slot   : PKCS#11 slot
 180       label  : PKCS#11 token label
 181 Notes:
 182   Please edit the vars script to reflect your configuration,
 183   then source it with "source ./vars".
 184   Next, to start with a fresh PKI configuration and to delete any
 185   previous certificates and keys, run "./clean-all".
 186   Finally, you can run this tool (pkitool) to build certificates/keys.
 187   In order to use PKCS#11 interface you must have opensc-0.10.0 or higher.
 188 Generated files and corresponding OpenVPN directives:
 189 (Files will be placed in the $KEY_DIR directory, defined in ./vars)
 190   ca.crt     -> root certificate (--ca)
 191   ca.key     -> root key, keep secure (not directly used by OpenVPN)
 192   .crt files -> client/server certificates (--cert)
 193   .key files -> private keys, keep secure (--key)
 194   .csr files -> certificate signing request (not directly used by OpenVPN)
 195   dh1024.pem or dh2048.pem -> Diffie Hellman parameters (--dh)
 196 Examples:
 197   pkitool --initca          -> Build root certificate
 198   pkitool --initca --pass   -> Build root certificate with password-protected key
 199   pkitool --server server1  -> Build "server1" certificate/key
 200   pkitool client1           -> Build "client1" certificate/key
 201   pkitool --pass client2    -> Build password-protected "client2" certificate/key
 202   pkitool --pkcs12 client3  -> Build "client3" certificate/key in PKCS#12 format
 203   pkitool --csr client4     -> Build "client4" CSR to be signed by another CA
 204   pkitool --sign client4    -> Sign "client4" CSR
 205   pkitool --inter interca   -> Build an intermediate key-signing certificate/key
 206                                Also see ./inherit-inter script.
 207   pkitool --pkcs11 /usr/lib/pkcs11/lib1 0 010203 "client5 id" client5
 208                               -> Build "client5" certificate/key in PKCS#11 token
 209 Typical usage for initial PKI setup.  Build myserver, client1, and client2 cert/keys.
 210 Protect client2 key with a password.  Build DH parms.  Generated files in ./keys :
 211   [edit vars with your site-specific info]
 212   source ./vars
 213   ./clean-all
 214   ./build-dh     -> takes a long time, consider backgrounding
 215   ./pkitool --initca
 216   ./pkitool --server myserver
 217   ./pkitool client1
 218   ./pkitool --pass client2
 219 Typical usage for adding client cert to existing PKI:
 220   source ./vars
 221   ./pkitool client-new