Skip to content

Commit

Permalink
[DOCS] Adds certutil http command to TLS setup steps (#51241)
Browse files Browse the repository at this point in the history
Co-Authored-By: Ioannis Kakavas <ikakavas@protonmail.com>
Co-Authored-By: Tim Vernum <tim@adjective.org>
  • Loading branch information
3 people committed Feb 21, 2020
1 parent 2774da6 commit 09b8a1f
Show file tree
Hide file tree
Showing 3 changed files with 70 additions and 39 deletions.
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
[[node-certificates]]
==== Generating 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
Expand Down Expand Up @@ -75,12 +75,27 @@ signing requests (CSR) for the nodes in your cluster. For more information, see
<<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
directory on each node. For example, `/home/es/config/certs`. There is no need
to copy the CA file to this directory.
For example, use the `elasticsearch-certutil http` command:

[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
certificates to the relevant configuration directory.
Expand Down
78 changes: 47 additions & 31 deletions x-pack/docs/en/security/securing-communications/tls-http.asciidoc
Original file line number Diff line number Diff line change
@@ -1,47 +1,63 @@
[role="xpack"]
[[tls-http]]
==== Encrypting HTTP Client communications
==== Encrypting HTTP client communications

When {security-features} are enabled, you can optionally use TLS to ensure that
communication between HTTP clients and the cluster is encrypted.

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
configuration changes in other parts of the Elastic Stack and in any {es}
clients that you use.
configuration changes in other parts of the {stack} and in any {es} clients that
you use.

. 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 node’s
certificate.
certificate. For example:

** If the certificate is in PKCS#12 format, add the following information to the
`elasticsearch.yml` file on each node:
.. Update the `elasticsearch.yml` file on each node with the location of the
certificates.
+
--
If the certificates are in PKCS#12 format:

[source, yaml]
--------------------------------------------------
xpack.security.http.ssl.enabled: true
xpack.security.http.ssl.keystore.path: certs/elastic-certificates.p12 <1>
xpack.security.http.ssl.truststore.path: certs/elastic-certificates.p12 <2>
xpack.security.http.ssl.keystore.path: "http.p12"
--------------------------------------------------
<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
`elasticsearch.yml` file on each node:
+
--
If you have certificates in PEM format:

[source, yaml]
--------------------------------------------------
xpack.security.http.ssl.enabled: true
xpack.security.http.ssl.key: /home/es/config/node01.key <1>
xpack.security.http.ssl.certificate: /home/es/config/node01.crt <2>
xpack.security.http.ssl.key: /home/es/config/node1_http.key <1>
xpack.security.http.ssl.certificate: /home/es/config/node1_http.crt <2>
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
Expand All @@ -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.
--

. If you secured the node's certificate with a password, add the password to
your {es} keystore:

** If the signed certificate is in PKCS#12 format, use the following commands:
.. If you secured the keystore or the private key with a password, add that password to a secure
setting in {es}.
+
--
If the certificates are in PKCS#12 format:

[source,shell]
-----------------------------------------------------------
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]
-----------------------------------------------------------
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}.

[NOTE]
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,8 @@ certificate.
-----------------------------------------------------------
xpack.security.transport.ssl.enabled: true
xpack.security.transport.ssl.verification_mode: certificate <1>
xpack.security.transport.ssl.keystore.path: certs/elastic-certificates.p12 <2>
xpack.security.transport.ssl.truststore.path: certs/elastic-certificates.p12 <3>
xpack.security.transport.ssl.keystore.path: elastic-certificates.p12 <2>
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
and you want to enable strict hostname checking, set the verification mode to
Expand All @@ -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
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
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
Expand Down

0 comments on commit 09b8a1f

Please sign in to comment.