[DOCS] Change certgen references to certutil (elastic/x-pack-elasticsearch#3415)

* [DOCS] Change certgen references to certutil

* [DOCS] Updated TLS page with certutil info

* [DOCS] Added certutil examples to TLS page

* [DOCS] Clarified PEM requirement in TLS setup

* [DOCS] Updated certificate instructions

* [DOCS] Fixed security typo

Original commit: elastic/x-pack-elasticsearch@3a326fc87d

docs/en/security/securing-communications/setting-up-ssl.asciidoc

@@ -20,7 +20,7 @@ the cluster:
 . Restart Elasticsearch.
 
 [[installing-node-certificates]]
-==== Node Certificates
+==== Generating Node Certificates
 
 TLS requires X.509 certificates to perform encryption and authentication of the application
 that is being communicated with. In order for the communication between nodes to be truly
@@ -29,20 +29,37 @@ certificate authenticity in a Elasticsearch cluster is to trust the certificate
 that signed the certificate. By doing this, as nodes are added to your cluster they just need
 to use a certificate signed by the same CA and the node is automatically allowed to join the
 cluster. Additionally, it is recommended that the certificates contain subject alternative
-names (SAN) that correspond to the node's ip address and dns name so that hostname verification
+names (SAN) that correspond to the node's IP address and DNS name so that hostname verification
 can be performed.
 
 In order to simplify the process of generating certificates for the Elastic Stack, a command
-line tool, `certgen` has been included with {xpack}. This tool takes care of the generating
+line tool, {ref}/certutil.html[`certutil`] has been included with {xpack}. This
-a CA and signing certificates with the CA. `certgen` can be used interactively or in a silent
+tool takes care of the generating
-mode through the use of an input file. The `certgen` tool also supports generation of certificate
+a CA and signing certificates with the CA. `certutil` can be used interactively or in a silent
-signing requests (CSR), so that a commercial or organization specific CA may be used to sign
+mode through the use of an input file. The `certutil` tool also supports generation of certificate
-the certificates. For more information, see {ref}/certgen.html[certgen].
+signing requests (CSR), so that a commercial or organization specific CA can be used to sign
+the certificates. For example:
 
-NOTE: If you choose not to use `certgen`, the certificates that you obtain must allow for both
+1. Optional: Create a certificate authority by using the `certutil ca` command.
+2. Generate a certificate for each node by using the `certutil cert` command.
++
+--
+NOTE: You should secure the output files, since they contain the private keys
+for your instance.
+
+--
+3. Copy the node certificate to the appropriate locations. For each Elastic
+product that you want to configure, copy the certificates to the relevant
+configuration directory. For more information, see
+<<enable-ssl,Configuring security in {es}>>,
+{kibana-ref}/using-kibana-with-security.html[Configuring security in {kib}], and
+{logstash-ref}/ls-security.html[Configuring security in Logstash].
+
+NOTE: If you choose not to use `certutil`, the certificates that you obtain must allow for both
 `clientAuth` and `serverAuth` if the extended key usage extension is present. The certificates
-need to be in PEM format. Although not required, it is highly recommended that the certificate contain
+need to be in PEM or PKCS#12 format. Although not required, it is highly recommended that the certificate contain
-the dns name(s) and/or ip address(es) of the node so that hostname verification may be used.
+the DNS names and/or IP addresses of the node so that hostname verification can be used.
+
 
 [[enable-ssl]]
 ==== Enabling SSL in the Node Configuration

docs/en/setup/installing-xes.asciidoc

@@ -146,11 +146,12 @@ the correct value for your environment, you may consider setting the value to
  `*` which will allow automatic creation of all indices.
 =============================================================================
 
-. Configure passwords and SSL/TLS.
+. Configure Transport Layer Security (TLS/SSL).
-.. If you have a non-trial license and you want to use {security}, you must
-configure SSL/TLS for internode-communication.
 +
 --
+If you have a non-trial license and you want to use {security}, you must
+configure TLS for internode-communication.
+
 NOTE: This requirement applies to clusters with more than one node and to
 clusters with a single node that listens on an external interface. Single-node
 clusters that use a loopback interface do not have this requirement.  For more
@@ -158,46 +159,97 @@ information, see
 {xpack-ref}/encrypting-communications.html[Encrypting Communications].
 
 --
-... Generate node certificates. For example, you can use the `certgen` command
+.. Generate node certificates. For example, you can use the `certutil` command
-line tool to generate a certificate authority and signed certificates for your
+line tool to generate a certificate authority (CA) and signed certificates for
-nodes.
+your nodes. For more information, see <<certutil>>.
+
+... Generate a new Certificate Authority (CA) for your {es} cluster:
 +
 --
 [source,shell]
 ----------------------------------------------------------
-bin/x-pack/certgen
+bin/x-pack/certutil ca
 ----------------------------------------------------------
-This command generates a zip file with the CA certificate, private key, and
-signed certificates and keys in the PEM format for each node that you specify.
-If you want to use a commercial or organization-specific CA, you can use the
-`-csr` parameter to generate certificate signing requests (CSR) for the nodes
-in your cluster. For more information, see <<certgen>>.
 
-TIP: For easier setup, use the node name as the instance name when you run
+You can configure the cluster to trust all nodes that have a certificate that
-this tool.
+has been signed by this CA.
 
+The command outputs a single file, with a default name of `elastic-stack-ca.p12`.
+This file is a PKCS#12 keystore that contains the public certificate for your CA
+and the private key that is used to sign the certificates for each node.
+
+The `certutil` command also prompts you for a password to protect the file and
+key. If you plan to add more nodes to your cluster in the future, retain a copy
+of the file and remember its password.
 --
-... Copy the certificate data into a directory within the {es} configuration
+
-directory. For example,
+... Generate a certificate and private key for each node in your cluster:
-`/home/es/config/certs`.
++
-... Add the following information to the `elasticsearch.yml` on all nodes:
+--
+[source,shell]
+----------------------------------------------------------
+bin/x-pack/certutil cert --ca elastic-stack-ca.p12
+----------------------------------------------------------
+The output is a single PKCS#12 keystore that includes the node certificate, node
+key, and CA certificate.
+
+You are also prompted for a password. You can enter a password for your
+certificate and key, or you can leave the password blank by pressing Enter.
+
+By default `certutil` generates certificates that have no hostname information
+in them (that is, they do not have any Subject Alternative Name fields).
+This means that you can use the certificate for every node in your cluster, but
+you must turn off hostname verification as shown in the configuration below.
+
+If you want to use hostname verification within your cluster, run the
+`certutil cert` command once for each of your nodes and provide the `--name`,
+`--dns` and `--ip` options.
+--
+... Alternatively, if you want to use a commercial or organization-specific CA,
+you can use the `certutil csr` command to generate certificate signing requests
+(CSR) for the nodes in your cluster. For more information, see <<certutil>>.
+
+.. Copy the applicable `.p12` file into a directory within the {es} configuration
+directory on each node. For example, `/home/es/config/certs`. There is no need
+to copy the CA file to this directory.
+
+.. Add the following information to the `elasticsearch.yml` file on each node:
 +
 --
 [source,yaml]
 -----------------------------------------------------------
-xpack.ssl.key: certs/${node.name}/${node.name}.key <1>
+xpack.ssl.keystore.path: certs/elastic-certificates.p12 <1>
-xpack.ssl.certificate: certs/${node.name}/${node.name}.crt <2>
+xpack.ssl.truststore.path: certs/elastic-certificates.p12 <2>
-xpack.ssl.certificate_authorities: certs/ca/ca.crt <3>
+xpack.security.transport.ssl.verification_mode: certificate <3>
 xpack.security.transport.ssl.enabled: true
 -----------------------------------------------------------
-<1> If this path does not exist on every node or the file name does not match
+<1> If you created a separate certificate for each node, then you might need to
-the `node.name` configuration setting, you must specify the full path to the
+customize this path on each node. If the filename matches the node name, you can
-node key file.
+use the `certs/${node.name}.p12` format, for example.
-<2> Alternatively, specify the full path to the node certificate.
+<2> The `certutil` output includes the CA certificate inside the PKCS#12
-<3> Alternatively specify the full path to the CA certificate.
+keystore, therefore the keystore can also be used as the truststore. This name
+should match the `keystore.path` value.
+<3> If you used the `--dns` or `--ip` options with the `certutil cert` command
+and you want to enable strict hostname checking, set the verification mode to
+`full`.
+
+For more information about these settings, see
+{ref}/security-settings.html[Security Settings in {es}].
 --
 
-.. Start {es}.
+.. If you secured the node's PKCS#12 file with a password, then you must add
+the password to your {es} keystore. Run the following commands:
++
+--
+[source,shell]
+-----------------------------------------------------------
+bin/elasticsearch-keystore add xpack.ssl.keystore.secure_password
+
+bin/elasticsearch-keystore add xpack.ssl.truststore.secure_password
+-----------------------------------------------------------
+--
+
+. Start {es}.
 +
 --
 [source,shell]
@@ -206,7 +258,7 @@ bin/elasticsearch
 ----------------------------------------------------------
 --
 
-.. Set the passwords for all built-in users. The +setup-passwords+ command is
+. Set the passwords for all built-in users. The +setup-passwords+ command is
 the simplest method to set the built-in users' passwords for the first time.
 +
 --