280 lines
11 KiB
Plaintext
280 lines
11 KiB
Plaintext
|
[role="xpack"]
|
||
|
|
[[certutil]]
|
||
|
|
== certutil
|
||
|
|
|
||
|
|
The `certutil` command simplifies the creation of certificates for use with
|
||
|
|
Transport Layer Security (TLS) in the Elastic Stack.
|
||
|
|
|
||
|
|
[float]
|
||
|
|
=== Synopsis
|
||
|
|
|
||
|
|
[source,shell]
|
||
|
|
--------------------------------------------------
|
||
|
|
bin/x-pack/certutil
|
||
|
|
(
|
||
|
|
(ca [--ca-dn <name>] [--days <n>] [--pem])
|
||
|
|
|
||
|
|
| (cert ([--ca <file_path>] | [--ca-cert <file_path> --ca-key <file_path>])
|
||
|
|
[--ca-dn <name>] [--ca-pass <password>] [--days <n>]
|
||
|
|
[--dns <domain_name>] [--in <input_file>] [--ip <ip_addresses>]
|
||
|
|
[--keep-ca-key] [--multiple] [--name <file_name>] [--pem])
|
||
|
|
|
||
|
|
| (csr [--dns <domain_name>] [--in <input_file>] [--ip <ip_addresses>]
|
||
|
|
[--name <file_name>])
|
||
|
|
|
||
|
|
[-E <KeyValuePair>] [--keysize <bits>] [--out <file_path>]
|
||
|
|
[--pass <password>]
|
||
|
|
)
|
||
|
|
[-h, --help] ([-s, --silent] | [-v, --verbose])
|
||
|
|
--------------------------------------------------
|
||
|
|
|
||
|
|
[float]
|
||
|
|
=== Description
|
||
|
|
|
||
|
|
You can specify one of the following modes: `ca`, `cert`, `csr`. The `certutil`
|
||
|
|
command also supports a silent mode of operation to enable easier batch
|
||
|
|
operations.
|
||
|
|
|
||
|
|
[float]
|
||
|
|
[[certutil-ca]]
|
||
|
|
==== CA mode
|
||
|
|
|
||
|
|
The `ca` mode generates a new certificate authority (CA). By default, it
|
||
|
|
produces a single PKCS#12 output file, which holds the CA certificate and the
|
||
|
|
private key for the CA. If you specify the `--pem` parameter, the command
|
||
|
|
generates a zip file, which contains the certificate and private key in PEM
|
||
|
|
format.
|
||
|
|
|
||
|
|
You can subsequently use these files as input for the `cert` mode of the command.
|
||
|
|
|
||
|
|
[float]
|
||
|
|
[[certutil-cert]]
|
||
|
|
==== CERT mode
|
||
|
|
|
||
|
|
The `cert` mode generates X.509 certificates and private keys. By default, it
|
||
|
|
produces a single certificate and key for use on a single instance.
|
||
|
|
|
||
|
|
To generate certificates and keys for multiple instances, specify the
|
||
|
|
`--multiple` parameter, which prompts you for details about each instance.
|
||
|
|
Alternatively, you can use the `--in` parameter to specify a YAML file that
|
||
|
|
contains details about the instances.
|
||
|
|
|
||
|
|
An instance is any piece of the Elastic Stack that requires a TLS or SSL
|
||
|
|
certificate. Depending on your configuration, {es}, Logstash, {kib}, and Beats
|
||
|
|
might all require a certificate and private key. The minimum required
|
||
|
|
information for an instance is its name, which is used as the common name for
|
||
|
|
the certificate. The instance name can be a hostname value or a full
|
||
|
|
distinguished name. If the instance name would result in an invalid file or
|
||
|
|
directory name, you must also specify a file name in the `--name` command
|
||
|
|
parameter or in the `filename` field in an input YAML file.
|
||
|
|
|
||
|
|
You can optionally provide IP addresses or DNS names for each instance. If
|
||
|
|
neither IP addresses nor DNS names are specified, the Elastic stack products
|
||
|
|
cannot perform hostname verification and you might need to configure the
|
||
|
|
`verfication_mode` security setting to `certificate` only. For more information
|
||
|
|
about this setting, see <<security-settings>>.
|
||
|
|
|
||
|
|
All certificates that are generated by this command are signed by a CA. You can
|
||
|
|
provide your own CA with the `--ca` or `--ca-cert` parameters. Otherwise, the
|
||
|
|
command automatically generates a new CA for you. For more information about
|
||
|
|
generating a CA, see the <<certutil-ca,CA mode of this command>>.
|
||
|
|
|
||
|
|
By default, the `cert` mode produces a single PKCS#12 output file which holds
|
||
|
|
the instance certificate, the instance private key, and the CA certificate. If
|
||
|
|
you specify the `--pem` parameter, the command generates PEM formatted
|
||
|
|
certificates and keys and packages them into a zip file. Likewise if you chose
|
||
|
|
to generate output for multiple instances, the command produces a zip file.
|
||
|
|
|
||
|
|
[float]
|
||
|
|
[[certutil-csr]]
|
||
|
|
==== CSR mode
|
||
|
|
|
||
|
|
The `csr` mode generates certificate signing requests (CSRs) that you can send
|
||
|
|
to a trusted certificate authority to obtain signed certificates. The signed
|
||
|
|
certificates must be in PEM or PKCS#12 format to work with {security}.
|
||
|
|
|
||
|
|
By default, the command produces a single CSR for a single instance.
|
||
|
|
|
||
|
|
To generate CSRs for multiple instances, specify the `--multiple` parameter,
|
||
|
|
which prompts you for details about each instance. Alternatively, you can use
|
||
|
|
the `--in` parameter to specify a YAML file that contains details about the
|
||
|
|
instances.
|
||
|
|
|
||
|
|
The `cert` mode produces a single zip file which contains the CSRs and the
|
||
|
|
private keys for each instance. Each CSR is provided as a standard PEM
|
||
|
|
encoding of a PKCS#10 CSR. Each key is provided as a PEM encoding of an RSA
|
||
|
|
private key.
|
||
|
|
|
||
|
|
[float]
|
||
|
|
=== Parameters
|
||
|
|
|
||
|
|
`ca`:: Specifies to generate a new local certificate authority (CA). This
|
||
|
|
parameter cannot be used with the `csr` or `cert` parameters.
|
||
|
|
|
||
|
|
`cert`:: Specifies to generate new X.509 certificates and keys.
|
||
|
|
This parameter cannot be used with the `csr` or `ca` parameters.
|
||
|
|
|
||
|
|
`csr`:: Specifies to generate certificate signing requests. This parameter
|
||
|
|
cannot be used with the `ca` or `cert` parameters.
|
||
|
|
|
||
|
|
`--ca <file_path>`:: Specifies the path to an existing CA key pair
|
||
|
|
(in PKCS#12 format). This parameter cannot be used with the `ca` or `csr` parameters.
|
||
|
|
|
||
|
|
`--ca-cert <file_path>`:: Specifies the path to an existing CA certificate (in
|
||
|
|
PEM format). You must also specify the `--ca-key` parameter. The `--ca-cert`
|
||
|
|
parameter cannot be used with the `ca` or `csr` parameters.
|
||
|
|
|
||
|
|
`--ca-dn <name>`:: Defines the _Distinguished Name_ (DN) that is used for the
|
||
|
|
generated CA certificate. The default value is
|
||
|
|
`CN=Elastic Certificate Tool Autogenerated CA`. This parameter cannot be used
|
||
|
|
with the `csr` parameter.
|
||
|
|
|
||
|
|
`--ca-key <file_path>`:: Specifies the path to an existing CA private key (in
|
||
|
|
PEM format). You must also specify the `--ca-cert` parameter. The `--ca-key`
|
||
|
|
parameter cannot be used with the `ca` or `csr` parameters.
|
||
|
|
|
||
|
|
`--ca-pass <password>`:: Specifies the password for an existing CA private key
|
||
|
|
or the generated CA private key. This parameter cannot be used with the `ca` or
|
||
|
|
`csr` parameters.
|
||
|
|
|
||
|
|
`--days <n>`:: Specifies an integer value that represents the number of days the
|
||
|
|
generated certificates are valid. The default value is `1095`. This parameter
|
||
|
|
cannot be used with the `csr` parameter.
|
||
|
|
|
||
|
|
`--dns <domain_name>`:: Specifies a comma-separated list of DNS names. This
|
||
|
|
parameter cannot be used with the `ca` parameter.
|
||
|
|
|
||
|
|
`-E <KeyValuePair>`:: Configures a setting.
|
||
|
|
|
||
|
|
`-h, --help`:: Returns all of the command parameters.
|
||
|
|
|
||
|
|
`--in <input_file>`:: Specifies the file that is used to run in silent mode. The
|
||
|
|
input file must be a YAML file. This parameter cannot be used with the `ca`
|
||
|
|
parameter.
|
||
|
|
|
||
|
|
`--ip <IP_addresses>`:: Specifies a comma-separated list of IP addresses. This
|
||
|
|
parameter cannot be used with the `ca` parameter.
|
||
|
|
|
||
|
|
`--keep-ca-key`:: When running in `cert` mode with an automatically-generated
|
||
|
|
CA, specifies to retain the CA private key for future use.
|
||
|
|
|
||
|
|
`--keysize <bits>`::
|
||
|
|
Defines the number of bits that are used in generated RSA keys. The default
|
||
|
|
value is `2048`.
|
||
|
|
|
||
|
|
`--multiple`::
|
||
|
|
Specifies to generate files for multiple instances. This parameter cannot be
|
||
|
|
used with the `ca` parameter.
|
||
|
|
|
||
|
|
`--name <file_name>`::
|
||
|
|
Specifies the name of the generated certificate. This parameter cannot be used
|
||
|
|
with the `ca` parameter.
|
||
|
|
|
||
|
|
`--out <file_path>`:: Specifies a path for the output files.
|
||
|
|
|
||
|
|
`--pass <password>`:: Specifies the password for the generated private keys.
|
||
|
|
|
||
|
|
`--pem`:: Generates certificates and keys in PEM format instead of PKCS#12. This
|
||
|
|
parameter cannot be used with the `csr` parameter.
|
||
|
|
|
||
|
|
`-s, --silent`:: Shows minimal output.
|
||
|
|
|
||
|
|
`-v, --verbose`:: Shows verbose output.
|
||
|
|
|
||
|
|
[float]
|
||
|
|
=== Examples
|
||
|
|
|
||
|
|
The following command generates a CA certificate and private key in PKCS#12
|
||
|
|
format:
|
||
|
|
|
||
|
|
[source, sh]
|
||
|
|
--------------------------------------------------
|
||
|
|
bin/x-pack/certutil ca
|
||
|
|
--------------------------------------------------
|
||
|
|
|
||
|
|
You are prompted for an output filename and a password. Alternatively, you can
|
||
|
|
specify the `--out` and `--pass` parameters.
|
||
|
|
|
||
|
|
You can then generate X.509 certificates and private keys by using the new
|
||
|
|
CA. For example:
|
||
|
|
|
||
|
|
[source, sh]
|
||
|
|
--------------------------------------------------
|
||
|
|
bin/x-pack/certutil cert --ca elastic-stack-ca.p12
|
||
|
|
--------------------------------------------------
|
||
|
|
|
||
|
|
You are prompted for the CA password and for an output filename and password.
|
||
|
|
Alternatively, you can specify the `--ca-pass`, `--out`, and `--pass` parameters.
|
||
|
|
|
||
|
|
By default, this command generates a file called `elastic-certificates.p12`,
|
||
|
|
which you can copy to the relevant configuration directory for each Elastic
|
||
|
|
product that you want to configure. For more information, see
|
||
|
|
{xpack-ref}/ssl-tls.html[Setting Up TLS on a Cluster].
|
||
|
|
|
||
|
|
[float]
|
||
|
|
[[certutil-silent]]
|
||
|
|
==== Using `certutil` in Silent Mode
|
||
|
|
|
||
|
|
To use the silent mode of operation, you must create a YAML file that contains
|
||
|
|
information about the instances. It must match the following format:
|
||
|
|
|
||
|
|
[source, yaml]
|
||
|
|
--------------------------------------------------
|
||
|
|
instances:
|
||
|
|
- name: "node1" <1>
|
||
|
|
ip: <2>
|
||
|
|
- "192.0.2.1"
|
||
|
|
dns: <3>
|
||
|
|
- "node1.mydomain.com"
|
||
|
|
- name: "node2"
|
||
|
|
ip:
|
||
|
|
- "192.0.2.2"
|
||
|
|
- "198.51.100.1"
|
||
|
|
- name: "node3"
|
||
|
|
- name: "node4"
|
||
|
|
dns:
|
||
|
|
- "node4.mydomain.com"
|
||
|
|
- "node4.internal"
|
||
|
|
- name: "CN=node5,OU=IT,DC=mydomain,DC=com"
|
||
|
|
filename: "node5" <4>
|
||
|
|
--------------------------------------------------
|
||
|
|
<1> The name of the instance. This can be a simple string value or can be a
|
||
|
|
Distinguished Name (DN). This is the only required field.
|
||
|
|
<2> An optional array of strings that represent IP Addresses for this instance.
|
||
|
|
Both IPv4 and IPv6 values are allowed. The values are added as Subject
|
||
|
|
Alternative Names.
|
||
|
|
<3> An optional array of strings that represent DNS names for this instance.
|
||
|
|
The values are added as Subject Alternative Names.
|
||
|
|
<4> The filename to use for this instance. This name is used as the name of the
|
||
|
|
directory that contains the instance's files in the output. It is also used in
|
||
|
|
the names of the files within the directory. This filename should not have an
|
||
|
|
extension. Note: If the `name` provided for the instance does not represent a
|
||
|
|
valid filename, then the `filename` field must be present.
|
||
|
|
|
||
|
|
When your YAML file is ready, you can use the `certutil` command to generate
|
||
|
|
certificates or certificate signing requests. Simply use the `--in` parameter to
|
||
|
|
specify the location of the file. For example:
|
||
|
|
|
||
|
|
[source, sh]
|
||
|
|
--------------------------------------------------
|
||
|
|
bin/x-pack/certutil cert --silent --in instances.yml --out test1.zip --pass testpassword
|
||
|
|
--------------------------------------------------
|
||
|
|
|
||
|
|
This command generates a compressed `test1.zip` file. After you decompress the
|
||
|
|
output file, there is a directory for each instance that was listed in the
|
||
|
|
`instances.yml` file. Each instance directory contains a single PKCS#12 (`.p12`)
|
||
|
|
file, which contains the instance certificate, instance private key, and CA
|
||
|
|
certificate.
|
||
|
|
|
||
|
|
You an also use the YAML file to generate certificate signing requests. For
|
||
|
|
example:
|
||
|
|
|
||
|
|
[source, sh]
|
||
|
|
--------------------------------------------------
|
||
|
|
bin/x-pack/certutil csr --silent --in instances.yml --out test2.zip --pass testpassword
|
||
|
|
--------------------------------------------------
|
||
|
|
|
||
|
|
This command generates a compressed file, which contains a directory for each
|
||
|
|
instance. Each instance directory contains a certificate signing request
|
||
|
|
(`*.csr` file) and private key (`*.key` file).
|