1Easy-RSA 3 Documentation Readme 2=============================== 3 4This document explains how Easy-RSA 3 and each of its assorted features work. 5 6If you are looking for a quickstart with less background or detail, an 7implementation-specific How-to or Readme may be available in this (the `doc/`) 8directory. 9 10Easy-RSA Overview 11----------------- 12 13Easy-RSA is a utility for managing X.509 PKI, or Public Key Infrastructure. A 14PKI is based on the notion of trusting a particular authority to authenticate a 15remote peer; for more background on how PKI works, see the `Intro-To-PKI` 16document. 17 18The code is written in platform-neutral POSIX shell, allowing use on a wide 19range of host systems. The official Windows release also comes bundled with the 20programs necessary to use Easy-RSA. The shell code attempts to limit the number 21of external programs it depends on. Crypto-related tasks use openssl as the 22functional backend. 23 24Feature Highlights 25------------------ 26 27Here's a non-exhaustive list of the more notable Easy-RSA features: 28 29 * Easy-RSA is able to manage multiple PKIs, each with their own independent 30 configuration, storage directory, and X.509 extension handling. 31 * Multiple Subject Name (X.509 DN field) formatting options are supported. For 32 VPNs, this means a cleaner commonName only setup can be used. 33 * A single backend is used across all supported platforms, ensuring that no 34 platform is 'left out' of the rich features. Unix-alikes (BSD, Linux, etc) 35 and Windows are all supported. 36 * Easy-RSA's X.509 support includes CRL, CDP, keyUsage/eKu attributes, and 37 additional features. The included support can be changed or extended as an 38 advanced feature. 39 * Interactive and automated (batch) modes of operation 40 * Flexible configuration: features can be enabled through command-line 41 options, environment variables, a config file, or a combination of these. 42 * Built-in defaults allow Easy-RSA to be used without first editing a config 43 file. 44 45Obtaining and Using Easy-RSA 46---------------------------- 47 48#### Download and extraction (installation) 49 50 Easy-RSA's main program is a script, supported by a couple of config files. As 51 such, there is no formal "installation" required. Preparing to use Easy-RSA is 52 as simple as downloading the compressed package (.tar.gz for Linux/Unix or 53 .zip for Windows) and extract it to a location of your choosing. There is no 54 compiling or OS-dependent setup required. 55 56 You should install and run Easy-RSA as a non-root (non-Administrator) account 57 as root access is not required. 58 59#### Running Easy-RSA 60 61 Invoking Easy-RSA is done through your preferred shell. Under Windows, you 62 will use the `EasyRSA Start.bat` program to provide a POSIX-shell environment 63 suitable for using Easy-RSA. 64 65 The basic format for running commands is: 66 67 ./easyrsa command [ cmd-opts ] 68 69 where `command` is the name of a command to run, and `cmd-opts` are any 70 options to supply to the command. Some commands have mandatory or optional 71 cmd-opts. Note the leading `./` component of the command: this is required in 72 Unix-like environments and may be a new concept to some Windows users. 73 74 General usage and command help can be shown with: 75 76 ./easyrsa help [ command ] 77 78 When run without any command, general usage and a list of available commands 79 are shown; when a command is supplied, detailed help output for that command 80 is shown. 81 82Configuring Easy-RSA 83-------------------- 84 85Easy-RSA 3 no longer needs any configuration file prior to operation, unlike 86earlier versions. However, the `vars.example` file contains many commented 87options that can be used to control non-default behavior as required. Reading 88this file will provide an idea of the basic configuration available. Note that 89a vars file must be named just `vars` (without an extension) to actively use it. 90 91Additionally, some options can be defined at runtime with options on the 92command-line. A full list can be shown with: 93 94 ./easyrsa help options 95 96Any of these options can appear before the command as required as shown below: 97 98 ./easyrsa [options] command [ cmd-opts ] 99 100For experts, additional configuration with env-vars and custom X.509 extensions 101is possible. Consult the `EasyRSA-Advanced` documentation for details. 102 103Getting Started: The Basics 104--------------------------- 105 106Some of the terms used here will be common to those familiar with how PKI works. 107Instead of describing PKI basics, please consult the document `Intro-To-PKI` if 108you need a more basic description of how a PKI works. 109 110#### Creating an Easy-RSA PKI 111 112 In order to do something useful, Easy-RSA needs to first initialize a 113 directory for the PKI. Multiple PKIs can be managed with a single installation 114 of Easy-RSA, but the default directory is called simply "pki" unless otherwise 115 specified. 116 117 To create or clear out (re-initialize) a new PKI, use the command: 118 119 ./easyrsa init-pki 120 121 which will create a new, blank PKI structure ready to be used. Once created, 122 this PKI can be used to make a new CA or generate keypairs. 123 124#### The PKI Directory Structure 125 126 An Easy-RSA PKI contains the following directory structure: 127 128 * private/ - dir with private keys generated on this host 129 * reqs/ - dir with locally generated certificate requests (for a CA imported 130 requests are stored here) 131 132 In a clean PKI no files exist yet, just the bare directories. Commands called 133 later will create the necessary files depending on the operation. 134 135 When building a CA, a number of new files are created by a combination of 136 Easy-RSA and (indirectly) openssl. The important CA files are: 137 138 * `ca.crt` - This is the CA certificate 139 * `index.txt` - This is the "master database" of all issued certs 140 * `serial` - Stores the next serial number (serial numbers increment) 141 * `private/ca.key` - This is the CA private key (security-critical) 142 * `certs_by_serial/` - dir with all CA-signed certs by serial number 143 * `issued/` - dir with issued certs by commonName 144 145#### After Creating a PKI 146 147 Once you have created a PKI, the next useful step will be to either create a 148 CA, or generate keypairs for a system that needs them. Continue with the 149 relevant section below. 150 151Using Easy-RSA as a CA 152---------------------- 153 154#### Building the CA 155 156 In order to sign requests to produce certificates, you need a CA. To create a 157 new CA in a PKI you have created, run: 158 159 ./easyrsa build-ca 160 161 Be sure to use a strong passphrase to protect the CA private key. Note that 162 you must supply this passphrase in the future when performing signing 163 operations with your CA, so be sure to remember it. 164 165 During the creation process, you will also select a name for the CA called the 166 Common Name (CN.) This name is purely for display purposes and can be set as 167 you like. 168 169#### Importing requests to the CA 170 171 Once a CA is built, the PKI is intended to be used to import requests from 172 external systems that are requesting a signed certificate from this CA. In 173 order to sign the request, it must first be imported so Easy-RSA knows about 174 it. This request file must be a standard CSR in PKCS#10 format. 175 176 Regardless of the file name to import, Easy-RSA uses a "short name" defined 177 during import to refer to this request. Importing works like this: 178 179 ./easyrsa import-req /path/to/request.req nameOfRequest 180 181 The nameOfRequest should normally refer to the system or person making the 182 request. 183 184#### Signing a request 185 186 Once Easy-RSA has imported a request, it can be reviewed and signed. Every 187 certificate needs a "type" which controls what extensions the certificate gets 188 Easy-RSA ships with 3 possible types: `client`, `server`, and `ca`, described 189 below: 190 191 * client - A TLS client, suitable for a VPN user or web browser (web client) 192 * server - A TLS server, suitable for a VPN or web server 193 * ca - A intermediate CA, used when chaining multiple CAs together 194 195 ./easyrsa sign-req <type> nameOfRequest 196 197 Additional types of certs may be defined by local sites as needed; see the 198 advanced documentation for details. 199 200#### Revoking and publishing CRLs 201 202 If an issue certificate needs to be revoked, this can be done as follows: 203 204 ./easyrsa revoke nameOfRequest 205 206 To generate a CRL suitable for publishing to systems that use it, run: 207 208 ./easyrsa gen-crl 209 210 Note that this will need to be published or sent to systems that rely on an 211 up-to-date CRL as the certificate is still valid otherwise. 212 213Using Easy-RSA to generate keypairs & requests 214---------------------------------------------- 215 216Easy-RSA can generate a keypair and certificate request in PKCS#10 format. This 217request is what a CA needs in order to generate and return a signed certificate. 218 219Ideally you should never generate entity keypairs for a client or server in a 220PKI you are using for your CA. It is best to separate this process and generate 221keypairs only on the systems you plan to use them. 222 223Easy-RSA can generate a keypair and request with the following command: 224 225 ./easyrsa gen-req nameOfRequest 226 227You will then be given a chance to modify the Subject details of your request. 228Easy-RSA uses the short name supplied on the command-line by default, though you 229are free to change it if necessary. After providing a passphrase and Subject 230details, the keypair and request files will be shown. 231 232In order to obtain a signed certificate, the request file must be sent to the 233CA for signing; this step is obviously not required if a single PKI is used as 234both the CA and keypair/request generation as the generated request is already 235"imported." 236 237