Easy-RSA Advanced Reference

This is a technical reference for advanced users familiar with PKI processes. If you need a more detailed description, see the EasyRSA-Readme or Intro-To-PKI docs instead.

Configuration Reference

Configuration Sources

There are 3 possible ways to perform external configuration of Easy-RSA, selected in the following order where the first defined result wins:

  1. Command-line option
  2. Environmental variable
  3. 'vars' file, if one is present (see vars Autodetection below)
  4. Built-in default

Note that not every possible config option can be set everywhere, although any env-var can be added to the 'vars' file even if it's not shown by default.

vars Autodetection

A 'vars' file is a file named simply vars (without an extension) that Easy-RSA will source for configuration. This file is specifically designed not to replace variables that have been set with a higher-priority method such as CLI opts or env-vars.

The following locations are checked, in this order, for a vars file. Only the first one found is used:

  1. The file referenced by the --vars CLI option
  2. The file referenced by the env-var named EASYRSA_VARS_FILE
  3. The directory referenced by the --pki CLI option (Recommended)
  4. The directory referenced by the EASYRSA_PKI env-var
  5. The directory referenced by the EASYRSA env-var
  6. The default PKI directory at $PWD/pki (See note below)
  7. The default working directory at $PWD

Defining the env-var EASYRSA_NO_VARS will override the sourcing of the vars file in all cases, including defining it subsequently as a global option.

Note: If the vars file $PWD/pki/vars is sourced then it is forbidden from setting/changing the current PKI, as defined by EASYRSA_PKI env-var.

Use of --pki verses --vars

It is recommended to use option --pki=DIR to define your PKI at runtime. This method will always auto-load the vars file found in the defined PKI.

In a multi-PKI installation, use of --vars can potentially lead to a vars file that is configured to set a PKI which cannot be verified as the expected PKI. Use of --vars is not recommended.

OpenSSL Config

Easy-RSA is tightly coupled to the OpenSSL config file (.cnf) for the flexibility the script provides. It is required that this file be available, yet it is possible to use a different OpenSSL config file for a particular PKI, or even change it for a particular invocation.

The OpenSSL config file is searched for in the following order:

  1. The env-var EASYRSA_SSL_CONF
  2. The 'vars' file (see vars Autodetection above)
  3. The EASYRSA_PKI directory with a filename of openssl-easyrsa.cnf
  4. The EASYRSA directory with a filename of openssl-easyrsa.cnf

Advanced extension handling

Normally the cert extensions are selected by the cert type given on the CLI during signing; this causes the matching file in the x509-types subdirectory to be processed for OpenSSL extensions to add. This can be overridden in a particular PKI by placing another x509-types dir inside the EASYRSA_PKI dir which will be used instead.

The file named COMMON in the x509-types dir is appended to every cert type; this is designed for CDP usage, but can be used for any extension that should apply to every signed cert.

Additionally, the contents of the env-var EASYRSA_EXTRA_EXTS is appended with its raw text added to the OpenSSL extensions. The contents are appended as-is to the cert extensions; invalid OpenSSL configs will usually result in failure.

Advanced configuration files

The following files are used by Easy-RSA to configure the SSL library: * openssl-easyrsa.cnf - Configuration for Certificate Authority [CA] * x509-types: COMMON, ca, server, serverClient, client, codeSigning, email. Each type is used to define an X509 purpose.

Since Easy-RSA version 3.2.0, these files are created on-demand by each command that requires them. However, if these files are found in one of the supported locations then those files are used instead, they are copied to temporary files. X509-type 'kdc' is only supported as an external file.

The supported locations are listed, in order of preference, as follows: * EASYRSA_PKI - Always preferred. * EASYRSA - For Windows. * PWD - For Windows. * easyrsa script directory - DEPRECATED, will be removed. Only for Windows. * /usr/local/share/easy-rsa * /usr/share/easy-rsa * /etc/easy-rsa

The x509-type files can be created by using command: easyrsa write legacy. To OVER-WRITE any existing files use command: eaysrsa write legacy-hard. This will create the files in the current PKI. If created then these new files take priority over system wide versions of the same files.

Environmental Variables Reference

A list of env-vars, any matching global option (CLI) to set/override it, and a short description is shown below:

NOTE: the global options must be provided before the commands.