[DOCS] Added certutil command (elastic/x-pack-elasticsearch#3294)
* [DOCS] Added certutil command * [DOCS] Added examples to certutil command * [DOCS] Address certutil feedback Original commit: elastic/x-pack-elasticsearch@a9df7bcda2
This commit is contained in:
Lisa Cawley
GitHub
parent
2ad6a3a538
commit
1cae1f8e93
|
|
@ -2,6 +2,8 @@
|
|||
[[certgen]]
|
||||
== certgen
|
||||
|
||||
deprecated[6.1,Replaced by <<certutil,`certutil`>>. ]
|
||||
|
||||
The `certgen` command simplifies the creation of certificate authorities (CA),
|
||||
certificate signing requests (CSR), and signed certificates for use with the
|
||||
Elastic Stack.
|
||||
|
|
@ -56,7 +58,7 @@ signed certificates must be in PEM format to work with {security}.
|
|||
using an existing CA certificate, which is provided in the `<cert_file>` argument.
|
||||
This parameter cannot be used with the `-csr` parameter.
|
||||
|
||||
`--csr`:: Specifies to operation in certificate signing request mode.
|
||||
`--csr`:: Specifies to operate in certificate signing request mode.
|
||||
|
||||
`--days <n>`::
|
||||
Specifies an integer value that represents the number of days the generated keys
|
||||
|
|
|
|||
|
|
@ -0,0 +1,279 @@
|
|||
[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).
|
||||
|
|
@ -8,6 +8,7 @@
|
|||
{xpack} includes commands that help you configure security:
|
||||
|
||||
* <<certgen>>
|
||||
* <<certutil>>
|
||||
* <<migrate-tool>>
|
||||
* <<setup-passwords>>
|
||||
* <<syskeygen>>
|
||||
|
|
@ -16,6 +17,7 @@
|
|||
--
|
||||
|
||||
include::certgen.asciidoc[]
|
||||
include::certutil.asciidoc[]
|
||||
include::migrate-tool.asciidoc[]
|
||||
include::setup-passwords.asciidoc[]
|
||||
include::syskeygen.asciidoc[]
|
||||
|
|
|
|||
Loading…
Reference in New Issue