[DOCS] Adds certutil http command to TLS setup steps (#51241)

Co-Authored-By: Ioannis Kakavas <ikakavas@protonmail.com>
Co-Authored-By: Tim Vernum <tim@adjective.org>
This commit is contained in:
Lisa Cawley 2020-02-21 10:04:29 -08:00 committed by lcawl
parent c4d91143ac
commit 56efd8b44d
3 changed files with 70 additions and 39 deletions

View File

@ -1,5 +1,5 @@
[[node-certificates]] [[node-certificates]]
==== Generating Node Certificates ==== Generating node certificates
TLS requires X.509 certificates to perform encryption and authentication of the TLS requires X.509 certificates to perform encryption and authentication of the
application that is being communicated with. In order for the communication application that is being communicated with. In order for the communication
@ -75,12 +75,27 @@ signing requests (CSR) for the nodes in your cluster. For more information, see
<<certutil>>. <<certutil>>.
-- --
. Copy the node certificate to the appropriate locations. . Optional: Generate additional certificates specifically for encrypting HTTP
client communications.
+ +
-- --
Copy the applicable `.p12` file into a directory within the {es} configuration For example, use the `elasticsearch-certutil http` command:
directory on each node. For example, `/home/es/config/certs`. There is no need
to copy the CA file to this directory. [source,shell]
----------------------------------------------------------
bin/elasticsearch-certutil http
----------------------------------------------------------
This command guides you through the process of generating the appropriate
certificates for use in {es} and {kib}. If you created a CA for your cluster,
you can re-use it by supplying its location when prompted.
--
. Copy the node certificates to the appropriate locations.
+
--
Copy the applicable files into the {es} configuration directory on each
node.
For each additional Elastic product that you want to configure, copy the For each additional Elastic product that you want to configure, copy the
certificates to the relevant configuration directory. certificates to the relevant configuration directory.

View File

@ -1,47 +1,63 @@
[role="xpack"] [role="xpack"]
[[tls-http]] [[tls-http]]
==== Encrypting HTTP Client communications ==== Encrypting HTTP client communications
When {security-features} are enabled, you can optionally use TLS to ensure that When {security-features} are enabled, you can optionally use TLS to ensure that
communication between HTTP clients and the cluster is encrypted. communication between HTTP clients and the cluster is encrypted.
NOTE: Enabling TLS on the HTTP layer is strongly recommended but is not required. NOTE: Enabling TLS on the HTTP layer is strongly recommended but is not required.
If you enable TLS on the HTTP layer in {es}, then you might need to make If you enable TLS on the HTTP layer in {es}, then you might need to make
configuration changes in other parts of the Elastic Stack and in any {es} configuration changes in other parts of the {stack} and in any {es} clients that
clients that you use. you use.
. If you have not done so already, <<node-certificates,generate node certificates>>. . If you have not done so already, <<node-certificates,generate node certificates>>.
+
--
In particular, you need the files that are generated by the following command:
[source,shell]
----------------------------------------------------------
bin/elasticsearch-certutil http
----------------------------------------------------------
This command generates a zip file that contains certificates and keys for use in
{es} and {kib}. Each folder contains a readme that explains how to use the files.
--
. Verify that you've copied the output files to the appropriate locations, as
specified in the readme files.
+
--
For example, copy the `http.p12` file from the `elasticsearch` folder into a
directory within the {es} configuration directory on each node. If you chose to
generate one certificate per node, copy the appropriate `http.p12` file to each
node. If you want to use {kib} to access this cluster, copy the
`elasticsearch-ca.pem` file from the `kibana` folder into the {kib}
configuration directory.
--
. Enable TLS and specify the information required to access the nodes . Enable TLS and specify the information required to access the nodes
certificate. certificate. For example:
** If the certificate is in PKCS#12 format, add the following information to the .. Update the `elasticsearch.yml` file on each node with the location of the
`elasticsearch.yml` file on each node: certificates.
+ +
-- --
If the certificates are in PKCS#12 format:
[source, yaml] [source, yaml]
-------------------------------------------------- --------------------------------------------------
xpack.security.http.ssl.enabled: true xpack.security.http.ssl.enabled: true
xpack.security.http.ssl.keystore.path: certs/elastic-certificates.p12 <1> xpack.security.http.ssl.keystore.path: "http.p12"
xpack.security.http.ssl.truststore.path: certs/elastic-certificates.p12 <2>
-------------------------------------------------- --------------------------------------------------
<1> If you created a separate certificate for each node, then you might need to
customize this path on each node. If the filename matches the node name, you can
use the `certs/${node.name}.p12` format, for example.
<2> The `elasticsearch-certutil` output includes the CA certificate inside the
PKCS#12 keystore, therefore the keystore can also be used as the truststore.
This name should match the `keystore.path` value.
--
** If the certificate is in PEM format, add the following information to the If you have certificates in PEM format:
`elasticsearch.yml` file on each node:
+
--
[source, yaml] [source, yaml]
-------------------------------------------------- --------------------------------------------------
xpack.security.http.ssl.enabled: true xpack.security.http.ssl.enabled: true
xpack.security.http.ssl.key: /home/es/config/node01.key <1> xpack.security.http.ssl.key: /home/es/config/node1_http.key <1>
xpack.security.http.ssl.certificate: /home/es/config/node01.crt <2> xpack.security.http.ssl.certificate: /home/es/config/node1_http.crt <2>
xpack.security.http.ssl.certificate_authorities: [ "/home/es/config/ca.crt" ] <3> xpack.security.http.ssl.certificate_authorities: [ "/home/es/config/ca.crt" ] <3>
-------------------------------------------------- --------------------------------------------------
<1> The full path to the node key file. This must be a location within the <1> The full path to the node key file. This must be a location within the
@ -52,29 +68,29 @@ xpack.security.http.ssl.certificate_authorities: [ "/home/es/config/ca.crt" ] <3
must be a location within the {es} configuration directory. must be a location within the {es} configuration directory.
-- --
. If you secured the node's certificate with a password, add the password to .. If you secured the keystore or the private key with a password, add that password to a secure
your {es} keystore: setting in {es}.
** If the signed certificate is in PKCS#12 format, use the following commands:
+ +
-- --
If the certificates are in PKCS#12 format:
[source,shell] [source,shell]
----------------------------------------------------------- -----------------------------------------------------------
bin/elasticsearch-keystore add xpack.security.http.ssl.keystore.secure_password bin/elasticsearch-keystore add xpack.security.http.ssl.keystore.secure_password
bin/elasticsearch-keystore add xpack.security.http.ssl.truststore.secure_password
----------------------------------------------------------- -----------------------------------------------------------
--
** If the certificate is in PEM format, use the following commands: If the certificates are in PEM format:
+
--
[source,shell] [source,shell]
----------------------------------------------------------- -----------------------------------------------------------
bin/elasticsearch-keystore add xpack.security.http.ssl.secure_key_passphrase bin/elasticsearch-keystore add xpack.security.http.ssl.secure_key_passphrase
----------------------------------------------------------- -----------------------------------------------------------
-- --
. Optional: If you want to use {kib}, follow the instructions in the readme
provided by the `elasticsearch-certutil http` command or see
{kibana-ref}/configuring-tls.html[Encrypting communications in {kib}].
. Restart {es}. . Restart {es}.
[NOTE] [NOTE]

View File

@ -19,8 +19,8 @@ certificate.
----------------------------------------------------------- -----------------------------------------------------------
xpack.security.transport.ssl.enabled: true xpack.security.transport.ssl.enabled: true
xpack.security.transport.ssl.verification_mode: certificate <1> xpack.security.transport.ssl.verification_mode: certificate <1>
xpack.security.transport.ssl.keystore.path: certs/elastic-certificates.p12 <2> xpack.security.transport.ssl.keystore.path: elastic-certificates.p12 <2>
xpack.security.transport.ssl.truststore.path: certs/elastic-certificates.p12 <3> xpack.security.transport.ssl.truststore.path: elastic-certificates.p12 <3>
----------------------------------------------------------- -----------------------------------------------------------
<1> If you used the `--dns` or `--ip` options with the `elasticsearch-certutil cert` command <1> If you used the `--dns` or `--ip` options with the `elasticsearch-certutil cert` command
and you want to enable strict hostname checking, set the verification mode to and you want to enable strict hostname checking, set the verification mode to
@ -29,7 +29,7 @@ See <<ssl-tls-settings, `xpack.security.transport.ssl.verification_mode`>> for a
<2> If you created a separate certificate for each node, then you might need to <2> If you created a separate certificate for each node, then you might need to
customize this path on each node. If the filename matches the node name, you can customize this path on each node. If the filename matches the node name, you can
use the `certs/${node.name}.p12` format, for example. use the `${node.name}.p12` format, for example.
<3> The `elasticsearch-certutil` outputs a PKCS#12 keystore which includes the <3> The `elasticsearch-certutil` outputs a PKCS#12 keystore which includes the
CA certificate as a trusted certificate entry. This allows for the keystore to CA certificate as a trusted certificate entry. This allows for the keystore to
also be used as a truststore. In this case, the path value should match also be used as a truststore. In this case, the path value should match