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:

 *  `EASYRSA` - should point to the Easy-RSA top-level dir, where the easyrsa
    script is located.
 *  `EASYRSA_OPENSSL` - command to invoke openssl
 *  `EASYRSA_SSL_CONF` - the openssl config file to use
 *  `EASYRSA_PKI` (CLI: `--pki`) - dir to use to hold all PKI-specific files,
     defaults to `$PWD/pki`.
 *  `EASYRSA_VARS_FILE` (CLI: `--vars`) - Set the `vars` file to use
 *  `EASYRSA_DN` (CLI: `--dn-mode`) - set to the string `cn_only` or `org` to
    alter the fields to include in the req DN
 *  `EASYRSA_REQ_COUNTRY` (CLI: `--req-c`) - set the DN country with org mode
 *  `EASYRSA_REQ_PROVINCE` (CLI: `--req-st`) - set the DN state/province with
    org mode
 *  `EASYRSA_REQ_CITY` (CLI: `--req-city`) - set the DN city/locality with org
    mode
 *  `EASYRSA_REQ_ORG` (CLI: `--req-org`) - set the DN organization with org mode
 *  `EASYRSA_REQ_EMAIL` (CLI: `--req-email`) - set the DN email with org mode
 *  `EASYRSA_REQ_OU` (CLI: `--req-ou`) - set the DN organizational unit with org
    mode
 *  `EASYRSA_REQ_SERIAL` (CLI: `--req-serial`) - set the DN serialNumber with
    org mode (OID 2.5.4.5)
 *  `EASYRSA_AUTO_SAN` (CLI: `--auto-san`) - use CN for SAN
 *  `EASYRSA_SAN` (CLI: `--san`) - Set subjectAltName for certificate
 *  `EASYRSA_SAN_CRIT` (CLI: `--san-crit`) - set the certificate SAN as 'critical'
 *  `EASYRSA_BC_CRIT` (CLI: `--bc-crit`) - set the certificate BC as 'critical'
 *  `EASYRSA_KU_CRIT` (CLI: `--ku-crit`) - set the certificate KU as 'critical'
 *  `EASYRSA_EKU_CRIT` (CLI: `--eku-crit`) - set the certificate EKU as 'critical'
 *  `EASYRSA_EXTRA_EXTS` - user defined extensions to add to the request or cert
 *  `EASYRSA_CP_EXT` (CLI: `--copy-ext`) - copy extensions from request to cert
 *  `EASYRSA_KEY_SIZE` (CLI: `--keysize`) - set the key size in bits to generate
 *  `EASYRSA_ALGO` (CLI: `--use-algo`) - set the crypto alg to use: rsa, ec or ed
 *  `EASYRSA_CURVE` (CLI: `--curve`) - define the named EC curve to use
 *  `EASYRSA_CA_EXPIRE` (CLI: `--days`) - set the CA expiration time in days
 *  `EASYRSA_CERT_EXPIRE` (CLI: `--days`) - set the cert expiration time in days
 *  `EASYRSA_CRL_DAYS` (CLI: `--days`) - set the CRL 'next publish' time in days
 *  `EASYRSA_NS_SUPPORT` (CLI: `--ns-cert`) - string 'yes' or 'no' fields to
    include the **deprecated** Netscape extensions
 *  `EASYRSA_NS_COMMENT` (CLI: `--ns-comment`) - string comment to include when
    using the **deprecated** Netscape extensions
 *  `EASYRSA_REQ_CN` (CLI: `--req-cn`) - default CN, can only be used in BATCH
    mode
 *  `EASYRSA_DIGEST` (CLI: `--digest`) - set a hash digest to use for req/cert
    signing
 *  `EASYRSA_BATCH` (CLI: `--batch`) - enable batch (no-prompt) mode; set
    env-var to non-zero string to enable (CLI takes no options)
 *  `EASYRSA_VERBOSE` (CLI: `-v`) - Enable verbose output
 *  `EASYRSA_PASSIN` (CLI: `--passin`) - allows to specify a source for
    password using any openssl password options like pass:1234 or env:var
 *  `EASYRSA_PASSOUT` (CLI: `--passout`) - allows to specify a source for
    password using any openssl password options like pass:1234 or env:var
 *  `EASYRSA_NO_PASS` (CLI: `--nopass`) - disable use of passwords
 *  `EASYRSA_UMASK` (CLI: `--umask`) - safe umask to use for file creation
    Defaults to `077`
 *  `EASYRSA_NO_UMASK` (CLI: `--no-umask`) - disable safe umask. Files will be
    created using the system's default
 *  `EASYRSA_TEMP_DIR` (CLI: `--tmp-dir`) - an existing directory to use for
    temporary files
 *  `EASYRSA_NO_INLINE` (CLI: `--no-inline`) - disable creation of inline files
 *  `EASYRSA_TEXT_ON` (CLI: `--text`) - include human readable text in SSL output
 *  `EASYRSA_TEXT_OFF` (CLI: `--notext`) - exclude human readable text from SSL
    output
 *  `EASYRSA_FORCE_SAFE_SSL` (CLI: `--force-safe-ssl`) - expand environment
    variables in SSL config
 *  `EASYRSA_FORCE_VARS` (CLI: `--force-vars`) - ignore known errors in 'vars' file
 *  `EASYRSA_SET_ERREXIT` - Enable `errexit`, IE. `set -e`, within `easyrsa` script

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