[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

docs/en/commands/certgen.asciidoc

@@ -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

docs/en/commands/certutil.asciidoc

@@ -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).

docs/en/commands/index.asciidoc

@@ -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[]