125 lines
5.6 KiB
Markdown
125 lines
5.6 KiB
Markdown
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 `EASYRSA_PKI` env-var
|
|
4. The default PKI directory at `$PWD/pki`
|
|
4. The directory referenced by the `EASYRSA` env-var
|
|
5. The directory containing the easyrsa program
|
|
|
|
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.
|
|
|
|
#### 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.
|
|
|
|
Environmental Variables Reference
|
|
---------------------------------
|
|
|
|
A list of env-vars, any matching global option (CLI) to set/override it, and a
|
|
possible terse 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`) - dir to use to hold all PKI-specific
|
|
files, defaults to `$PWD/pki`.
|
|
* `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_KEY_SIZE` (CLI: `--key-size`) - set the key size in bits to
|
|
generate
|
|
* `EASYRSA_ALGO` (CLI: `--use-algo`) - set the crypto alg to use: rsa or ec
|
|
* `EASYRSA_CURVE` (CLI: `--curve`) - define the named EC curve to use
|
|
* `EASYRSA_EC_DIR` - dir to store generated ecparams
|
|
* `EASYRSA_CA_EXPIRE` (CLI: `--days`) - set the CA expiration time in days
|
|
* `EASYRSA_CERT_EXPIRE` (CLI: `--days`) - set the issued 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_TEMP_FILE` - a temp file to use when dynamically creating req/cert
|
|
extensions
|
|
* `EASYRSA_REQ_CN` (CLI: `--req-cn`) - default CN, necessary to set 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_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
|
|
|
|
**NOTE:** the global options need to be provided before the actual commands.
|