From f81e1f1ad326dfa8072abc661f41ec0aa360e5c9 Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Fri, 4 Jun 2021 14:00:53 -0400 Subject: [PATCH 01/24] [DOCS] Steps for updating TLS certificates --- x-pack/docs/en/security/index.asciidoc | 2 + .../update-tls-certificates.asciidoc | 237 ++++++++++++++++++ 2 files changed, 239 insertions(+) create mode 100644 x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc diff --git a/x-pack/docs/en/security/index.asciidoc b/x-pack/docs/en/security/index.asciidoc index 98503f823373e..a8a563ca93faf 100644 --- a/x-pack/docs/en/security/index.asciidoc +++ b/x-pack/docs/en/security/index.asciidoc @@ -92,6 +92,8 @@ See <>. include::configuring-stack-security.asciidoc[] +include::securing-communications/update-tls-certificates.asciidoc[] + include::authentication/overview.asciidoc[] include::authorization/overview.asciidoc[] diff --git a/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc b/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc new file mode 100644 index 0000000000000..9f1f11f3e74ee --- /dev/null +++ b/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc @@ -0,0 +1,237 @@ +[[update-node-certs]] +== Updating node security certificates +When updating your node security certificates, there are two main scenarios that +you'll encounter: + +* <> +* <> + +Regardless of the scenario, {es} monitors the SSL resources for updates +on a five-second interval. You can just copy the new certificate and key files +(or keystore) into the appropriate location and your nodes will detect the +changes. + +Because {es} doesn't reload the `elasticsearch.yml` configuration, +you must use *the same file names* so that {es} refreshes the security +certificates and keys. + +IMPORTANT: If you need to change a password for a key, keystore, or truststore +that is stored in the <>, then you must restart +the cluster. {es} will not reload changes for passwords stored in the secure +settings. We recommend rolling restarts when restarting the cluster. + +.Rolling restarts are preferred +**** +While it's possible to do an in-place update for security certificates, using +a <> on your cluster is safer. An in-place update avoids some +complications of a rolling restart, but incurs the following risks: + +* If you use PEM files, your certificate and key are in separate files. You +must update both files _simultaneously_ or the node might experience a temporary +period where it cannot establish new connections. +* Updating the certificate and key does not automatically force existing +connections to refresh. This means that even if you make a mistake, a node can +seem like it's functioning but only because it still has existing connections. +It's possible that a node will be unable to connect with other nodes, rendering +it unable to recover from a network outage or node restart. +**** + +[[update-node-certs-same]] +=== Update security certificates with the same CA +++++ +With the same CA +++++ + +If your CA hasn't changed, you can just generate a new certificate, save it with +the same name as your existing certificate, and replace the existing file. +You'll need to generate new certificates and keys for both the transport layer +and the HTTP layer. + +This procedure assumes that the you have access to the CA certificate and key +that was originally generated (or otherwise held by your organization) and used +to sign the certificate that is currently in use. It also assumes that the +clients connecting to {es} on the HTTP layer are configured to trust the CA +certificate. + +TIP: If your CA has changed, complete the steps in +<>. + +[discrete] +[[node-certs-same-transport]] +==== Generate a new certificate for the transport layer +Create a new PKCS#12 file that contains the a certificate and key and replace +the existing PKCS#12 file (such as `elastic-certificates.p12`) with the new +certificate. + +NOTE: The following examples use PKCS#12 files, but the same steps apply to JKS keystores. + +. Open the `ES_PATH_CONF/elasticsearch.yml` file and check the names of the +security certificates that are currently in use. You'll use the same names +for your new certificate. ++ +In this example, the keystore and truststore are pointing to different files. +Your configuration might use the same file that contains the certificate and CA. ++ +[source,yaml] +---- +xpack.security.transport.ssl.keystore.path: config/elastic-certificates.p12 +xpack.security.transport.ssl.keystore.type: PKCS12 +xpack.security.transport.ssl.keystore.password: password +xpack.security.transport.ssl.truststore.path: config/elastic-ca.p12 +xpack.security.transport.ssl.truststore.type: PKCS12 +xpack.security.transport.ssl.truststore.password: password +---- + +. Generate a certificate and private key for your node. You must include the CA +that was used to sign the certificate currently in use. ++ + `--ca `:: Name of the CA file used to sign your certificates. The + default file name from the `elasticsearch-certutil` tool is `elastic-stack-ca.p12`. ++ +[source,shell] +---- +./bin/elasticsearch-certutil cert --ca elastic-stack-ca.p12 +---- + + a. Enter the password for your CA when prompted. + + b. Enter the name for your certificate, which must match the name of the + certificate currently in use. + + c. (Optional) Enter a password for your certificate. + +. If you entered a password when creating the node certificate, run the following commands to store the password in the {es} keystore: ++ +-- +[source,shell] +---- +./bin/elasticsearch-keystore add xpack.security.transport.ssl.keystore.secure_password +---- + +[source,shell] +---- +./bin/elasticsearch-keystore add xpack.security.transport.ssl.truststore.secure_password +---- +-- + +. [[cert-password-updates]] If your certificate is password protected, the password is stored in the {es} keystore, _and_ the password needs to change, then you must perform a <> on your cluster. Complete the steps until the step that indicates *Perform any needed changes*, and then continue to the next step to replace your existing certificates. + +. Replace your existing certificate with the new certificate, ensuring that the +file names match. + +. Repeat the previous step on each node in your cluster to update the existing certificate, completing a rolling restart beforehand if your certificate matches the password stipulations outlined in <>. + +[discrete] +[[node-certs-same-http]] +==== Generate a new certificate for the HTTP layer +This certificate is used to verify other components when they connect to {es}. + +. Stop {es} and {kib} if they are running. + +. From the directory where you installed {es}, run the {es} HTTP certificate +tool. ++ +[source,shell] +---- +./bin/elasticsearch-certutil http +---- ++ +This command generates a `.zip` file that contains certificates and keys +to use with {es} and {kib}. Each folder contains a `README.txt` +explaining how to use these files. + + a. When asked if you want to generate a CSR, enter `n`. + + b. When asked if you want to use an existing CA, enter `y`. + + c. Enter the absolute path to your CA, such as the path to the + `elastic-stack-ca.p12` file. + + d. Enter the password for your CA. + + e. Enter an expiration value for your certificate. You can enter the + validity period in years, months, or days. For example, enter `90D` for 90 + days. + + f. When asked if you want to generate one certificate per node, enter `y`. ++ +Each certificate will have its own private key, and will be issued for a +specific hostname or IP address. + + g. When prompted, enter the name of the first node in your cluster. Use the same node name that you used when <>. + + h. Enter all hostnames used to connect to your first node. These hostnames + will be added as DNS names in the Subject Alternative Name (SAN) field in your certificate. ++ +List every hostname and variant used to connect to your cluster over HTTPS. + + i. Enter the IP addresses that clients can use to connect to your node. + + j. Repeat these steps for each additional node in your cluster. + +. After generating a certificate for each of your nodes, enter a password for + your private key when prompted. + +. Unzip the generated `elasticsearch-ssl-http.zip` file. This compressed file + contains one directory for both {es} and {kib}. ++ +-- +[source,txt] +---- +/elasticsearch +|_ README.txt +|_ http.p12 +|_ sample-elasticsearch.yml +---- + +[source,txt] +---- +/kibana +|_ README.txt +|_ elasticsearch-ca.pem +|_ sample-kibana.yml +---- +-- + +. Rename the `http.p12` file to match the name of your existing certificate for +HTTP client communications. + +. On each node, edit the `elasticsearch.yml` file to enable HTTPS security and + specify the location of the `http.p12` security certificate. ++ +[source,yaml] +---- +xpack.security.http.ssl.enabled: true +xpack.security.http.ssl.keystore.path: .p12 +---- + +. Add the password for your private key to the secure settings in {es}. ++ +[source,shell] +---- +./bin/elasticsearch-keystore add xpack.security.http.ssl.keystore.secure_password +---- + +. [[cert-password-updates-https]] If your certificate is password protected, the password is stored in the {es} keystore, _and_ the password needs to change, then you must perform a <> on your cluster. Complete the steps until the step that indicates *Perform any needed changes*, and then continue to the next step to replace your existing certificates. + +. Replace your existing certificate with the new certificate, ensuring that the +file names match. ++ +{es} will reload the file and its configuration and start presenting the new +certificate to the incoming TLS connections. + +. Repeat the previous step on each node in your cluster to update the existing certificate, completing a rolling restart beforehand if your certificate matches the password stipulations outlined in <>. + +[[update-node-certs-different]] +=== Update security certificates with a different CA +++++ +With a different CA +++++ + +[discrete] +[[node-certs-different-transport]] +==== Generate a new certificate for the transport layer + +[discrete] +[[node-certs-different-http]] +==== Generate a new certificate for the HTTP layer \ No newline at end of file From 5d8cd30ed5a48c6defce84ee6ee9dc8aaf9e2e15 Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Mon, 7 Jun 2021 16:50:03 -0400 Subject: [PATCH 02/24] Updates for changing CA --- .../security-basic-setup.asciidoc | 10 ++- .../update-tls-certificates.asciidoc | 77 +++++++++++++++++-- 2 files changed, 77 insertions(+), 10 deletions(-) diff --git a/x-pack/docs/en/security/securing-communications/security-basic-setup.asciidoc b/x-pack/docs/en/security/securing-communications/security-basic-setup.asciidoc index 4426dcdec7890..9e5c3abe23c40 100644 --- a/x-pack/docs/en/security/securing-communications/security-basic-setup.asciidoc +++ b/x-pack/docs/en/security/securing-communications/security-basic-setup.asciidoc @@ -89,8 +89,13 @@ generate a CA for your cluster. + [source,shell] ---- -./bin/elasticsearch-certutil cert --ca elastic-stack-ca.p12 +./bin/elasticsearch-certutil cert --ca elastic-stack-ca.p12 --pem ---- ++ + `--ca `:: Name of the CA file used to sign your certificates. The + default file name from the `elasticsearch-certutil` tool is `elastic-stack-ca.p12`. + `--pem`:: ++ a. Enter the password for your CA, or press *Enter* if you did not configure one in the previous step. @@ -98,9 +103,6 @@ generate a CA for your cluster. + The output file is a keystore named `elastic-certificates.p12`. This file contains a node certificate, node key, and CA certificate. -+ - `--ca `:: Name of the CA file used to sign your certificates. The - default file name from the `elasticsearch-certutil` tool is `elastic-stack-ca.p12`. . Copy the `elastic-certificates.p12` file to the `ES_PATH_CONF` directory on every node in your cluster. diff --git a/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc b/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc index 9f1f11f3e74ee..7ec5b9873ed4a 100644 --- a/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc +++ b/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc @@ -82,19 +82,20 @@ xpack.security.transport.ssl.truststore.type: PKCS12 xpack.security.transport.ssl.truststore.password: password ---- -. Generate a certificate and private key for your node. You must include the CA -that was used to sign the certificate currently in use. -+ - `--ca `:: Name of the CA file used to sign your certificates. The - default file name from the `elasticsearch-certutil` tool is `elastic-stack-ca.p12`. +. On any node in your cluster, generate a certificate and private key for your +node. You must include the CA that was used to sign the certificate currently +in use. + [source,shell] ---- ./bin/elasticsearch-certutil cert --ca elastic-stack-ca.p12 ---- ++ + `--ca `:: Name of the CA file used to sign your certificates. The + default file name from the `elasticsearch-certutil` tool is `elastic-stack-ca.p12`. a. Enter the password for your CA when prompted. - + b. Enter the name for your certificate, which must match the name of the certificate currently in use. @@ -231,6 +232,70 @@ certificate to the incoming TLS connections. [discrete] [[node-certs-different-transport]] ==== Generate a new certificate for the transport layer +If your CA is changing or has already changed, you'll need to generate a new +CA key and certificate. You can then add this CA certificate to all nodes so +that they know and trust it. Then, generate new certificate/key pairs for each +node that are signed by the new CA and instruct your nodes to use the new files. + +NOTE: The following examples use PKCS#12 files, but the same steps apply to JKS keystores. + +. Open the `ES_PATH_CONF/elasticsearch.yml` file and check the names of the +security certificates that are currently in use. You'll use the same names +for your new certificate. ++ +In this example, the keystore and truststore are pointing to different files. +Your configuration might use the same file that contains the certificate and CA. ++ +[source,yaml] +---- +xpack.security.transport.ssl.keystore.path: config/elastic-certificates.p12 +xpack.security.transport.ssl.keystore.type: PKCS12 +xpack.security.transport.ssl.keystore.password: password +xpack.security.transport.ssl.truststore.path: config/elastic-ca.p12 +xpack.security.transport.ssl.truststore.type: PKCS12 +xpack.security.transport.ssl.truststore.password: password +---- + +. On any node in your cluster, generate a new certificate and private key. You +only need to complete this step once, and can use the generated security files +on every node in your cluster. ++ +You must include the CA that was used to sign the certificate currently in use. ++ +[source,shell] +---- +./bin/elasticsearch-certutil cert --ca elastic-stack-ca.p12 --pem +---- + + `--ca `:: Name of the CA file used to sign your certificates. The + default file name from the `elasticsearch-certutil` tool is `elastic-stack-ca.p12`. + `--pem`:: Generates an `/instance` directory containing a new certificate and + key in PEM format instead of PKCS#12. + + a. Enter the password for your CA when prompted. + + b. Enter a name for the compressed output file that will contain your + certificate and key, or accept the default name of `certificate-bundle.zip`. + + c. Unzip the output file. The + resulting directory contains two files: `instance.crt` and `instance.key`. ++ +-- +IMPORTANT: Keep these file in a secure location as they contain the private key +for your instance. +-- + +. On every node in your cluster, import the new `instance.crt` certificate into your +existing CA certificate. This step ensures that your nodes trust the new +certificate. This example uses the Java `keytool` utility to import the +certificate into the `elasticsearch-certificates.p12` CA certificate. ++ +[source,shell] +---- +keytool -importcert -trustcacerts -noprompt -keystore elasticsearch-certificates.p12 \ +-storepass passw0rd -alias testca -file instance.crt +---- + [discrete] [[node-certs-different-http]] From 81d1708022c6304072394b4d05b36c59513f4dde Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Tue, 8 Jun 2021 17:03:37 -0400 Subject: [PATCH 03/24] Updates for rotating certs with a new CA --- .../update-tls-certificates.asciidoc | 170 +++++++++++++++--- 1 file changed, 141 insertions(+), 29 deletions(-) diff --git a/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc b/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc index 7ec5b9873ed4a..4e52390c2c98d 100644 --- a/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc +++ b/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc @@ -54,7 +54,7 @@ clients connecting to {es} on the HTTP layer are configured to trust the CA certificate. TIP: If your CA has changed, complete the steps in -<>. +<>. [discrete] [[node-certs-same-transport]] @@ -228,74 +228,186 @@ certificate to the incoming TLS connections. ++++ With a different CA ++++ +If your CA needs to change or has already changed, you'll need to generate a new +CA certificate and key. You can then add this CA certificate to your existing CA +truststore so that all nodes in your cluster so know and trust it. Then, +generate new certificate/key pairs for each node that are signed by the new CA +and instruct your nodes to use the new files. [discrete] [[node-certs-different-transport]] ==== Generate a new certificate for the transport layer -If your CA is changing or has already changed, you'll need to generate a new -CA key and certificate. You can then add this CA certificate to all nodes so -that they know and trust it. Then, generate new certificate/key pairs for each -node that are signed by the new CA and instruct your nodes to use the new files. +Create a new CA and add it to your existing CA truststore. NOTE: The following examples use PKCS#12 files, but the same steps apply to JKS keystores. . Open the `ES_PATH_CONF/elasticsearch.yml` file and check the names of the security certificates that are currently in use. You'll use the same names -for your new certificate. +for your new certificates. + -In this example, the keystore and truststore are pointing to different files. -Your configuration might use the same file that contains the certificate and CA. +In this example, the keystore and truststore are using different files. +Your configuration might use the same file for both the keystore and the +truststore. We recommend using separate files. + [source,yaml] ---- xpack.security.transport.ssl.keystore.path: config/elastic-certificates.p12 xpack.security.transport.ssl.keystore.type: PKCS12 xpack.security.transport.ssl.keystore.password: password -xpack.security.transport.ssl.truststore.path: config/elastic-ca.p12 +xpack.security.transport.ssl.truststore.path: config/elastic-stack-ca.p12 xpack.security.transport.ssl.truststore.type: PKCS12 xpack.security.transport.ssl.truststore.password: password ---- -. On any node in your cluster, generate a new certificate and private key. You -only need to complete this step once, and can use the generated security files -on every node in your cluster. +. On *any* node in your cluster, generate a new CA. You only need to complete +this step once. + -You must include the CA that was used to sign the certificate currently in use. +NOTE: If your organization has its own CA, then use that CA to generate a new +CA certificate in PEM format. + [source,shell] ---- -./bin/elasticsearch-certutil cert --ca elastic-stack-ca.p12 --pem +./bin/elasticsearch-certutil ca --pem ---- - `--ca `:: Name of the CA file used to sign your certificates. The - default file name from the `elasticsearch-certutil` tool is `elastic-stack-ca.p12`. - `--pem`:: Generates an `/instance` directory containing a new certificate and + `--pem`:: Generates a directory containing a CA certificate and key in PEM format instead of PKCS#12. - - a. Enter the password for your CA when prompted. - b. Enter a name for the compressed output file that will contain your - certificate and key, or accept the default name of `certificate-bundle.zip`. + a. Enter a name for the compressed output file that will contain your + certificate and key, or accept the default name of `elastic-stack-ca.zip`. - c. Unzip the output file. The - resulting directory contains two files: `instance.crt` and `instance.key`. + b. Unzip the output file. The + resulting directory contains two files: `ca.crt` and `ca.key`. + -- IMPORTANT: Keep these file in a secure location as they contain the private key -for your instance. +for your CA. -- -. On every node in your cluster, import the new `instance.crt` certificate into your -existing CA certificate. This step ensures that your nodes trust the new +. On *every* node in your cluster, import the new `ca.crt` certificate into your +existing CA truststore. This step ensures that your cluster trusts the new CA certificate. This example uses the Java `keytool` utility to import the -certificate into the `elasticsearch-certificates.p12` CA certificate. +certificate into the `elastic-stack-ca.p12` CA truststore. ++ +[source,shell] +---- +keytool -importcert -trustcacerts -noprompt -keystore elastic-stack-ca.p12 \ +-storepass -alias new-ca -file ca.crt +---- + + `-alias`:: Name that you want to assign to the new CA certificate. + +. Check that the new CA certificate was added to your truststore. The output +should contain both the existing CA certificate and your new certificate. Each +CA certificate is identified by the `friendlyName` attribute in the output. ++ +[source,shell] +---- +openssl pkcs12 -info -in config/elastic-stack-ca.p12 +---- + +[discrete] +[[node-certs-different-nodes]] +==== Generate a new certificate for each node in your cluster +Now that your CA truststore is updated, use your new CA certificate to sign +a certificate for each node in your cluster. Rather than run the +`elasticsearch-certutil` tool once for each node, create an `instances.yml` file +that contains information about each of your nodes. You can then use the +`elasticsearch-certutil` tool to generate certificates for all of your nodes +with a single command. + +. Create an `instances.yml` file that contains information about each of your +nodes. Include all IP addresses and DNS names that you use to identify each +node. ++ +[source,yaml] +---- +instances: + - name: "node1" + ip: + - "192.168.1.101" + dns: + - "node1" + - "node1.mydomain.com" + - name: "node2" + ip: + - "192.168.1.102" + dns: + - "node2" + - "node2.mydomain.com" + - name: "node3" + ip: + - "192.168.1.103" + dns: + - "node3" + - "node3.mydomain.com" + - name: "node4" + ip: + - "192.168.1.104" + dns: + - "node4" + - "node4.mydomain.com" +---- + +. Using the new CA certificate and key, create a new certificate for each node +in your cluster. Include the `instances.yml` file that you created previously. ++ +[source,shell] +---- +./bin/elasticsearch-certutil cert --in instances.yml --ca-cert ca/ca.crt \ +--ca-key ca/ca.key +---- + + `-in`:: Specifies the name of the input YAML file containing information + about each of your nodes. + + `--ca-cert`:: Specifies the path to your new CA certificate (in PEM format). + You must also specify the `--ca-key` parameter. + + `--ca-key`:: Specifies the path to the private key for your CA certificate. + You must also specify the `--ca-cert` parameter. + + a. Enter a name for the output file or accept the default of + `certificate-bundle.zip`. + + b. When prompted, enter a password for each node certificate. It's good + practice to use a different password for each node certificate and store the + files in a secure location. + + c. Decompress the `certificate-bundle.zip` file. The output contains a + directory for each of your nodes with a `.p12` file. + +. On *every* node, copy the appropriate node certificate to the `ES_PATH_CONF` +directory. ++ +NOTE: The `ES_PATH_CONF` variable is the path for the {es} +configuration files. If you installed {es} using archive distributions +(`zip` or `tar.gz`), the variable defaults to `ES_HOME/config`. If you used +package distributions (Debian or RPM), the variable defaults to `/etc/elasticsearch`. + +. On *every* node, modify the `elasticsearch.yml` file to update the +`keystore.path` variable with the name of the new node certificate. For example, +`node-1.p12`. ++ +[source,yaml] +---- +xpack.security.transport.ssl.keystore.path: config/node-1.p12 +xpack.security.transport.ssl.keystore.type: PKCS12 +xpack.security.transport.ssl.keystore.password: password +---- + +. Delete the old node certificates from each node. + +. (Optional) Remove the old CA certificate from your truststore. + [source,shell] ---- -keytool -importcert -trustcacerts -noprompt -keystore elasticsearch-certificates.p12 \ --storepass passw0rd -alias testca -file instance.crt +keytool -delete -noprompt -alias ca -keystore config/elastic-stack-ca.p12 \ +-storepass ---- + `-alias`:: Name of the old CA certificate that you want to remove from you + truststore. [discrete] [[node-certs-different-http]] From 7674c7567698189d8dd9217bcd67b5a5cb688df4 Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Wed, 9 Jun 2021 19:18:34 -0400 Subject: [PATCH 04/24] Add instructions for generating HTTP certs with a new CA --- .../update-tls-certificates.asciidoc | 160 ++++++++++++++---- 1 file changed, 124 insertions(+), 36 deletions(-) diff --git a/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc b/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc index 4e52390c2c98d..3cce66542c13a 100644 --- a/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc +++ b/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc @@ -56,7 +56,6 @@ certificate. TIP: If your CA has changed, complete the steps in <>. -[discrete] [[node-certs-same-transport]] ==== Generate a new certificate for the transport layer Create a new PKCS#12 file that contains the a certificate and key and replace @@ -91,9 +90,11 @@ in use. ./bin/elasticsearch-certutil cert --ca elastic-stack-ca.p12 ---- + +==== `--ca `:: Name of the CA file used to sign your certificates. The default file name from the `elasticsearch-certutil` tool is `elastic-stack-ca.p12`. - +==== ++ a. Enter the password for your CA when prompted. b. Enter the name for your certificate, which must match the name of the @@ -122,7 +123,6 @@ file names match. . Repeat the previous step on each node in your cluster to update the existing certificate, completing a rolling restart beforehand if your certificate matches the password stipulations outlined in <>. -[discrete] [[node-certs-same-http]] ==== Generate a new certificate for the HTTP layer This certificate is used to verify other components when they connect to {es}. @@ -197,14 +197,11 @@ List every hostname and variant used to connect to your cluster over HTTPS. . Rename the `http.p12` file to match the name of your existing certificate for HTTP client communications. -. On each node, edit the `elasticsearch.yml` file to enable HTTPS security and - specify the location of the `http.p12` security certificate. +. Replace your existing certificate with the new certificate, ensuring that the +file names match. + -[source,yaml] ----- -xpack.security.http.ssl.enabled: true -xpack.security.http.ssl.keystore.path: .p12 ----- +{es} will reload the file and its configuration and start presenting the new +certificate to the incoming TLS connections. . Add the password for your private key to the secure settings in {es}. + @@ -215,13 +212,7 @@ xpack.security.http.ssl.keystore.path: .p12 . [[cert-password-updates-https]] If your certificate is password protected, the password is stored in the {es} keystore, _and_ the password needs to change, then you must perform a <> on your cluster. Complete the steps until the step that indicates *Perform any needed changes*, and then continue to the next step to replace your existing certificates. -. Replace your existing certificate with the new certificate, ensuring that the -file names match. -+ -{es} will reload the file and its configuration and start presenting the new -certificate to the incoming TLS connections. - -. Repeat the previous step on each node in your cluster to update the existing certificate, completing a rolling restart beforehand if your certificate matches the password stipulations outlined in <>. +. Repeat the previous steps on each node in your cluster to update the existing certificate, completing a rolling restart beforehand if your certificate matches the password stipulations outlined in <>. [[update-node-certs-different]] === Update security certificates with a different CA @@ -234,12 +225,12 @@ truststore so that all nodes in your cluster so know and trust it. Then, generate new certificate/key pairs for each node that are signed by the new CA and instruct your nodes to use the new files. -[discrete] [[node-certs-different-transport]] ==== Generate a new certificate for the transport layer -Create a new CA and add it to your existing CA truststore. +Create a new CA certificate and add it to your existing CA truststore. -NOTE: The following examples use PKCS#12 files, but the same steps apply to JKS keystores. +NOTE: The following examples use PKCS#12 files, but the same steps apply to JKS +keystores. . Open the `ES_PATH_CONF/elasticsearch.yml` file and check the names of the security certificates that are currently in use. You'll use the same names @@ -269,10 +260,12 @@ CA certificate in PEM format. ---- ./bin/elasticsearch-certutil ca --pem ---- - ++ +==== `--pem`:: Generates a directory containing a CA certificate and key in PEM format instead of PKCS#12. - +==== + a. Enter a name for the compressed output file that will contain your certificate and key, or accept the default name of `elastic-stack-ca.zip`. @@ -294,8 +287,10 @@ certificate into the `elastic-stack-ca.p12` CA truststore. keytool -importcert -trustcacerts -noprompt -keystore elastic-stack-ca.p12 \ -storepass -alias new-ca -file ca.crt ---- - ++ +==== `-alias`:: Name that you want to assign to the new CA certificate. +==== . Check that the new CA certificate was added to your truststore. The output should contain both the existing CA certificate and your new certificate. Each @@ -306,6 +301,19 @@ CA certificate is identified by the `friendlyName` attribute in the output. openssl pkcs12 -info -in config/elastic-stack-ca.p12 ---- +. (Optional) Remove the old CA certificate from your truststore. ++ +[source,shell] +---- +keytool -delete -noprompt -alias old-ca -keystore config/elastic-stack-ca.p12 \ +-storepass +---- ++ +==== + `-alias`:: Name of the old CA certificate that you want to remove from your + truststore. +==== + [discrete] [[node-certs-different-nodes]] ==== Generate a new certificate for each node in your cluster @@ -357,7 +365,8 @@ in your cluster. Include the `instances.yml` file that you created previously. ./bin/elasticsearch-certutil cert --in instances.yml --ca-cert ca/ca.crt \ --ca-key ca/ca.key ---- - ++ +==== `-in`:: Specifies the name of the input YAML file containing information about each of your nodes. @@ -366,6 +375,7 @@ in your cluster. Include the `instances.yml` file that you created previously. `--ca-key`:: Specifies the path to the private key for your CA certificate. You must also specify the `--ca-cert` parameter. +==== a. Enter a name for the output file or accept the default of `certificate-bundle.zip`. @@ -385,9 +395,9 @@ configuration files. If you installed {es} using archive distributions (`zip` or `tar.gz`), the variable defaults to `ES_HOME/config`. If you used package distributions (Debian or RPM), the variable defaults to `/etc/elasticsearch`. -. On *every* node, modify the `elasticsearch.yml` file to update the -`keystore.path` variable with the name of the new node certificate. For example, -`node-1.p12`. +. If the name of your new node certificate doesn't match the name of the +existing certificate, modify the `elasticsearch.yml` file to update the +`keystore.path` variable with the new name. For example, `node-1.p12`. + [source,yaml] ---- @@ -396,19 +406,97 @@ xpack.security.transport.ssl.keystore.type: PKCS12 xpack.security.transport.ssl.keystore.password: password ---- -. Delete the old node certificates from each node. +. Delete the old node certificate from each node. -. (Optional) Remove the old CA certificate from your truststore. +[[node-certs-different-http]] +==== Generate a new certificate for the HTTP layer +This certificate is used to verify other components when they connect to {es}. + +. Stop {es} and {kib} if they are running. + +. From the directory where you installed {es}, run the {es} HTTP certificate +tool. + [source,shell] ---- -keytool -delete -noprompt -alias ca -keystore config/elastic-stack-ca.p12 \ --storepass +./bin/elasticsearch-certutil http ---- ++ +This command generates a `.zip` file that contains certificates and keys +to use with {es} and {kib}. Each folder contains a `README.txt` +explaining how to use these files. - `-alias`:: Name of the old CA certificate that you want to remove from you - truststore. + a. When asked if you want to generate a CSR, enter `n`. -[discrete] -[[node-certs-different-http]] -==== Generate a new certificate for the HTTP layer \ No newline at end of file + b. When asked if you want to use an existing CA, enter `y`. + + c. Enter the absolute path to your *new* CA certificate, such as the path to + the `ca.crt` file. + + d. Enter the absolute path to your new CA certificate private key, such as + the path to the `ca.key` file. + + e. Enter an expiration value for your certificate. You can enter the + validity period in years, months, or days. For example, enter `90D` for 90 + days. + + f. When asked if you want to generate one certificate per node, enter `y`. ++ +Each certificate will have its own private key, and will be issued for a +specific hostname or IP address. + + g. When prompted, enter the name of the first node in your cluster. Use the same node name that you used when <>. + + h. Enter all hostnames used to connect to your first node. These hostnames + will be added as DNS names in the Subject Alternative Name (SAN) field in your certificate. ++ +List every hostname and variant used to connect to your cluster over HTTPS. + + i. Enter the IP addresses that clients can use to connect to your node. + + j. Repeat these steps for each additional node in your cluster. + +. After generating a certificate for each of your nodes, enter a password for + your private key when prompted. + +. Unzip the generated `elasticsearch-ssl-http.zip` file. This compressed file + contains one directory for both {es} and {kib}. Additionally, a directory is + created for each node that you specified with it's own `http.p12` file. ++ +-- +[source,txt] +---- +/elasticsearch +|_ README.txt +|_ http.p12 +|_ sample-elasticsearch.yml +---- + +[source,txt] +---- +/kibana +|_ README.txt +|_ elasticsearch-ca.pem +|_ sample-kibana.yml +---- +-- + +. Rename the `http.p12` file to match the name of your existing certificate for +HTTP client communications. + +. Replace your existing certificate with the new certificate, ensuring that the +file names match. ++ +{es} will reload the file and its configuration and start presenting the new +certificate to the incoming TLS connections. + +. Add the password for your private key to the secure settings in {es}. ++ +[source,shell] +---- +./bin/elasticsearch-keystore add xpack.security.http.ssl.keystore.secure_password +---- + +. [[cert-password-updates-https]] If your certificate is password protected, the password is stored in the {es} keystore, _and_ the password needs to change, then you must perform a <> on your cluster. Complete the steps until the step that indicates *Perform any needed changes*, and then continue to the next step to replace your existing certificates. + +. Repeat the previous steps on each node in your cluster to update the existing certificate, completing a rolling restart beforehand if your certificate matches the password stipulations outlined in <>. \ No newline at end of file From 7313c4b2344df9fc37bad56f2f7b660b8b3338b8 Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Thu, 10 Jun 2021 10:33:01 -0400 Subject: [PATCH 05/24] Add steps for creating HTTP certs with new CA --- .../update-tls-certificates.asciidoc | 66 +++++++++++++------ 1 file changed, 46 insertions(+), 20 deletions(-) diff --git a/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc b/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc index 3cce66542c13a..1782c423e1ebb 100644 --- a/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc +++ b/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc @@ -90,6 +90,8 @@ in use. ./bin/elasticsearch-certutil cert --ca elastic-stack-ca.p12 ---- + +[%collapsible%open] +.Command parameters ==== `--ca `:: Name of the CA file used to sign your certificates. The default file name from the `elasticsearch-certutil` tool is `elastic-stack-ca.p12`. @@ -125,7 +127,8 @@ file names match. [[node-certs-same-http]] ==== Generate a new certificate for the HTTP layer -This certificate is used to verify other components when they connect to {es}. +This certificate is used to verify other components when they connect to {es}, +such as {kib} or any of the Elastic language clients. . Stop {es} and {kib} if they are running. @@ -159,7 +162,9 @@ explaining how to use these files. Each certificate will have its own private key, and will be issued for a specific hostname or IP address. - g. When prompted, enter the name of the first node in your cluster. Use the same node name that you used when <>. + g. When prompted, enter the name of the first node in your cluster. Use the + same node name as the value for the `node.name` parameter in the + `elasticsearch.yml` file. h. Enter all hostnames used to connect to your first node. These hostnames will be added as DNS names in the Subject Alternative Name (SAN) field in your certificate. @@ -250,8 +255,8 @@ xpack.security.transport.ssl.truststore.type: PKCS12 xpack.security.transport.ssl.truststore.password: password ---- -. On *any* node in your cluster, generate a new CA. You only need to complete -this step once. +. On *any* node in your cluster, generate a new CA certificate. You only need +to complete this step once. + NOTE: If your organization has its own CA, then use that CA to generate a new CA certificate in PEM format. @@ -261,6 +266,8 @@ CA certificate in PEM format. ./bin/elasticsearch-certutil ca --pem ---- + +[%collapsible%open] +.Command parameters ==== `--pem`:: Generates a directory containing a CA certificate and key in PEM format instead of PKCS#12. @@ -269,8 +276,8 @@ CA certificate in PEM format. a. Enter a name for the compressed output file that will contain your certificate and key, or accept the default name of `elastic-stack-ca.zip`. - b. Unzip the output file. The - resulting directory contains two files: `ca.crt` and `ca.key`. + b. Unzip the output file. The resulting directory contains a CA certificate + (`ca.crt`) and private key (`ca.key`). + -- IMPORTANT: Keep these file in a secure location as they contain the private key @@ -288,14 +295,25 @@ keytool -importcert -trustcacerts -noprompt -keystore elastic-stack-ca.p12 \ -storepass -alias new-ca -file ca.crt ---- + +[%collapsible%open] +.Command parameters ==== + `-keystore`:: Name of the truststore that you are importing the new CA + certificate into. + + `-storepass`:: Password for the CA truststore. + `-alias`:: Name that you want to assign to the new CA certificate. + + `-file`:: Name of the new CA certificate to import. ==== . Check that the new CA certificate was added to your truststore. The output should contain both the existing CA certificate and your new certificate. Each CA certificate is identified by the `friendlyName` attribute in the output. + +When prompted, enter the password for the CA truststore. ++ [source,shell] ---- openssl pkcs12 -info -in config/elastic-stack-ca.p12 @@ -309,6 +327,8 @@ keytool -delete -noprompt -alias old-ca -keystore config/elastic-stack-ca.p12 \ -storepass ---- + +[%collapsible%open] +.Command parameters ==== `-alias`:: Name of the old CA certificate that you want to remove from your truststore. @@ -324,9 +344,9 @@ that contains information about each of your nodes. You can then use the `elasticsearch-certutil` tool to generate certificates for all of your nodes with a single command. -. Create an `instances.yml` file that contains information about each of your -nodes. Include all IP addresses and DNS names that you use to identify each -node. +. On any node in your cluster, create an `instances.yml` file that contains +information about each of your nodes. Include all IP addresses and DNS names +that you use to identify each node. + [source,yaml] ---- @@ -366,15 +386,17 @@ in your cluster. Include the `instances.yml` file that you created previously. --ca-key ca/ca.key ---- + +[%collapsible%open] +.Command parameters ==== - `-in`:: Specifies the name of the input YAML file containing information - about each of your nodes. + `-in`:: Specifies the name of the input YAML file (`instances.yml`) + containing information about each of your nodes. - `--ca-cert`:: Specifies the path to your new CA certificate (in PEM format). - You must also specify the `--ca-key` parameter. + `--ca-cert`:: Specifies the path to your new CA certificate (`ca.crt`) in PEM + format. You must also specify the `--ca-key` parameter. - `--ca-key`:: Specifies the path to the private key for your CA certificate. - You must also specify the `--ca-cert` parameter. + `--ca-key`:: Specifies the path to the private key (`ca.key`) for your CA + certificate. You must also specify the `--ca-cert` parameter. ==== a. Enter a name for the output file or accept the default of @@ -410,7 +432,9 @@ xpack.security.transport.ssl.keystore.password: password [[node-certs-different-http]] ==== Generate a new certificate for the HTTP layer -This certificate is used to verify other components when they connect to {es}. +You can generate certificates for the HTTP layer using your new CA certificate +and private key. This certificate is used to verify other components when they +connect to {es}, such as {kib} or any of the Elastic language clients. . Stop {es} and {kib} if they are running. @@ -445,7 +469,9 @@ explaining how to use these files. Each certificate will have its own private key, and will be issued for a specific hostname or IP address. - g. When prompted, enter the name of the first node in your cluster. Use the same node name that you used when <>. + g. When prompted, enter the name of the first node in your cluster. Use the + same node name as the value for the `node.name` parameter in the + `elasticsearch.yml` file. h. Enter all hostnames used to connect to your first node. These hostnames will be added as DNS names in the Subject Alternative Name (SAN) field in your certificate. @@ -457,7 +483,7 @@ List every hostname and variant used to connect to your cluster over HTTPS. j. Repeat these steps for each additional node in your cluster. . After generating a certificate for each of your nodes, enter a password for - your private key when prompted. + your keystore when prompted. . Unzip the generated `elasticsearch-ssl-http.zip` file. This compressed file contains one directory for both {es} and {kib}. Additionally, a directory is @@ -497,6 +523,6 @@ certificate to the incoming TLS connections. ./bin/elasticsearch-keystore add xpack.security.http.ssl.keystore.secure_password ---- -. [[cert-password-updates-https]] If your certificate is password protected, the password is stored in the {es} keystore, _and_ the password needs to change, then you must perform a <> on your cluster. Complete the steps until the step that indicates *Perform any needed changes*, and then continue to the next step to replace your existing certificates. +. [[cert-password-update-https]] If your certificate is password protected, the password is stored in the {es} keystore, _and_ the password needs to change, then you must perform a <> on your cluster. Complete the steps until the step that indicates *Perform any needed changes*, and then continue to the next step to replace your existing certificates. -. Repeat the previous steps on each node in your cluster to update the existing certificate, completing a rolling restart beforehand if your certificate matches the password stipulations outlined in <>. \ No newline at end of file +. Repeat the previous steps on each node in your cluster to update the existing certificate, completing a rolling restart beforehand if your certificate matches the password stipulations outlined in <>. \ No newline at end of file From 4ad7ca98b6d0782b2035ec8962848b88a91e6e03 Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Thu, 10 Jun 2021 13:55:36 -0400 Subject: [PATCH 06/24] Clarify note about cluser restart and other edits --- .../update-tls-certificates.asciidoc | 43 +++++++++++-------- 1 file changed, 24 insertions(+), 19 deletions(-) diff --git a/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc b/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc index 1782c423e1ebb..02d32924efb16 100644 --- a/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc +++ b/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc @@ -15,11 +15,21 @@ Because {es} doesn't reload the `elasticsearch.yml` configuration, you must use *the same file names* so that {es} refreshes the security certificates and keys. -IMPORTANT: If you need to change a password for a key, keystore, or truststore +[IMPORTANT] +==== +The following changes require a cluster restart. We recommend +<> when restarting your cluster. + +* If you updates your nodes with certificates using different file names than +the ones specified in `elasticsearch.yml`, you must update that file with the +location of the new certificates. +* If you need to change a password for a key, keystore, or truststore that is stored in the <>, then you must restart the cluster. {es} will not reload changes for passwords stored in the secure -settings. We recommend rolling restarts when restarting the cluster. +settings. +==== +[[use-rolling-restarts]] .Rolling restarts are preferred **** While it's possible to do an in-place update for security certificates, using @@ -227,12 +237,14 @@ certificate to the incoming TLS connections. If your CA needs to change or has already changed, you'll need to generate a new CA certificate and key. You can then add this CA certificate to your existing CA truststore so that all nodes in your cluster so know and trust it. Then, -generate new certificate/key pairs for each node that are signed by the new CA -and instruct your nodes to use the new files. +generate a new certificate for each node that are signed by the new CA +certificate and instruct your nodes to use the new files. [[node-certs-different-transport]] ==== Generate a new certificate for the transport layer -Create a new CA certificate and add it to your existing CA truststore. +Create a new CA certificate and add it to your existing CA truststore. After +{es} reloads the file, you can remove the old CA certificate from your +truststore. NOTE: The following examples use PKCS#12 files, but the same steps apply to JKS keystores. @@ -256,7 +268,7 @@ xpack.security.transport.ssl.truststore.password: password ---- . On *any* node in your cluster, generate a new CA certificate. You only need -to complete this step once. +to complete this step one time. + NOTE: If your organization has its own CA, then use that CA to generate a new CA certificate in PEM format. @@ -269,8 +281,8 @@ CA certificate in PEM format. [%collapsible%open] .Command parameters ==== - `--pem`:: Generates a directory containing a CA certificate and - key in PEM format instead of PKCS#12. + `--pem`:: Generates a directory containing a CA certificate and key in PEM + format instead of PKCS#12. ==== a. Enter a name for the compressed output file that will contain your @@ -409,6 +421,10 @@ in your cluster. Include the `instances.yml` file that you created previously. c. Decompress the `certificate-bundle.zip` file. The output contains a directory for each of your nodes with a `.p12` file. + d. Rename the `.p12` file to match the existing file name + specified by the `xpack.security.transport.ssl.keystore.path` variable in + the `elasticsearch.yml` file. + . On *every* node, copy the appropriate node certificate to the `ES_PATH_CONF` directory. + @@ -417,17 +433,6 @@ configuration files. If you installed {es} using archive distributions (`zip` or `tar.gz`), the variable defaults to `ES_HOME/config`. If you used package distributions (Debian or RPM), the variable defaults to `/etc/elasticsearch`. -. If the name of your new node certificate doesn't match the name of the -existing certificate, modify the `elasticsearch.yml` file to update the -`keystore.path` variable with the new name. For example, `node-1.p12`. -+ -[source,yaml] ----- -xpack.security.transport.ssl.keystore.path: config/node-1.p12 -xpack.security.transport.ssl.keystore.type: PKCS12 -xpack.security.transport.ssl.keystore.password: password ----- - . Delete the old node certificate from each node. [[node-certs-different-http]] From f2205ef9335d18e1571f478ca6bfc667a674b02e Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Thu, 10 Jun 2021 15:21:06 -0400 Subject: [PATCH 07/24] Clarifying scenarios --- .../update-tls-certificates.asciidoc | 36 +++++++++---------- 1 file changed, 16 insertions(+), 20 deletions(-) diff --git a/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc b/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc index 02d32924efb16..6e3a232e474ca 100644 --- a/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc +++ b/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc @@ -1,33 +1,28 @@ [[update-node-certs]] == Updating node security certificates -When updating your node security certificates, there are two main scenarios that -you'll encounter: +If your cluster certificates expired or you have a new Certificate Authority +(CA), then you'll need to update the security certificates for both the +transport and HTTP layers. When updating your node security certificates, there +are two main scenarios that you'll encounter: * <> * <> Regardless of the scenario, {es} monitors the SSL resources for updates on a five-second interval. You can just copy the new certificate and key files -(or keystore) into the appropriate location and your nodes will detect the -changes. +(or keystore) into the {es} configuration directory and your nodes will detect +the changes. Because {es} doesn't reload the `elasticsearch.yml` configuration, you must use *the same file names* so that {es} refreshes the security -certificates and keys. +certificates and keys. This method of updating certificates is preferred +because it doesn't require a full cluster restart. -[IMPORTANT] -==== -The following changes require a cluster restart. We recommend -<> when restarting your cluster. - -* If you updates your nodes with certificates using different file names than -the ones specified in `elasticsearch.yml`, you must update that file with the -location of the new certificates. -* If you need to change a password for a key, keystore, or truststore -that is stored in the <>, then you must restart -the cluster. {es} will not reload changes for passwords stored in the secure -settings. -==== +If you need to update the `elasticsearch.yml` configuration or change +certificate passwords that are stored in the +<>, then you must complete a full cluster +restart. {es} will not reload changes for passwords stored in the secure +settings. We recommend <> when restarting your cluster. [[use-rolling-restarts]] .Rolling restarts are preferred @@ -68,7 +63,7 @@ TIP: If your CA has changed, complete the steps in [[node-certs-same-transport]] ==== Generate a new certificate for the transport layer -Create a new PKCS#12 file that contains the a certificate and key and replace +Create a new PKCS#12 file that contains a certificate and key and replace the existing PKCS#12 file (such as `elastic-certificates.p12`) with the new certificate. @@ -104,7 +99,8 @@ in use. .Command parameters ==== `--ca `:: Name of the CA file used to sign your certificates. The - default file name from the `elasticsearch-certutil` tool is `elastic-stack-ca.p12`. + default file name from the `elasticsearch-certutil` tool is + `elastic-stack-ca.p12`. ==== + a. Enter the password for your CA when prompted. From 6cd5cecebe3d228c13b0ec46db93877ecc49654c Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Mon, 21 Jun 2021 11:07:13 -0400 Subject: [PATCH 08/24] Apply suggestions from code review Co-authored-by: Ioannis Kakavas --- .../update-tls-certificates.asciidoc | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc b/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc index 6e3a232e474ca..b777ee39788a9 100644 --- a/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc +++ b/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc @@ -1,7 +1,7 @@ [[update-node-certs]] == Updating node security certificates If your cluster certificates expired or you have a new Certificate Authority -(CA), then you'll need to update the security certificates for both the +(CA), then you'll need to update the certificates for both the transport and HTTP layers. When updating your node security certificates, there are two main scenarios that you'll encounter: @@ -70,7 +70,7 @@ certificate. NOTE: The following examples use PKCS#12 files, but the same steps apply to JKS keystores. . Open the `ES_PATH_CONF/elasticsearch.yml` file and check the names of the -security certificates that are currently in use. You'll use the same names +keystores that are currently in use. You'll use the same names for your new certificate. + In this example, the keystore and truststore are pointing to different files. @@ -98,17 +98,17 @@ in use. [%collapsible%open] .Command parameters ==== - `--ca `:: Name of the CA file used to sign your certificates. The + `--ca `:: Name of the CA keystore used to sign your certificates. The default file name from the `elasticsearch-certutil` tool is `elastic-stack-ca.p12`. ==== + - a. Enter the password for your CA when prompted. + a. Enter the password for your CA keystore when prompted. - b. Enter the name for your certificate, which must match the name of the - certificate currently in use. + b. Enter the name for your keystore, which must match the name of the + keystore currently in use. - c. (Optional) Enter a password for your certificate. + c. (Optional) Enter a password for your keystore. . If you entered a password when creating the node certificate, run the following commands to store the password in the {es} keystore: + @@ -124,7 +124,7 @@ in use. ---- -- -. [[cert-password-updates]] If your certificate is password protected, the password is stored in the {es} keystore, _and_ the password needs to change, then you must perform a <> on your cluster. Complete the steps until the step that indicates *Perform any needed changes*, and then continue to the next step to replace your existing certificates. +. [[cert-password-updates]] If your keystore is password protected, the password is stored in the {es} keystore, _and_ the password needs to change, then you must perform a <> on your cluster. Complete the steps until the step that indicates *Perform any needed changes*, and then continue to the next step to replace your existing certificates. . Replace your existing certificate with the new certificate, ensuring that the file names match. @@ -526,4 +526,4 @@ certificate to the incoming TLS connections. . [[cert-password-update-https]] If your certificate is password protected, the password is stored in the {es} keystore, _and_ the password needs to change, then you must perform a <> on your cluster. Complete the steps until the step that indicates *Perform any needed changes*, and then continue to the next step to replace your existing certificates. -. Repeat the previous steps on each node in your cluster to update the existing certificate, completing a rolling restart beforehand if your certificate matches the password stipulations outlined in <>. \ No newline at end of file +. Repeat the previous steps on each node in your cluster to update the existing certificate, completing a rolling restart beforehand if your certificate matches the password stipulations outlined in <>. From 86e02a549b42d9094190e487a42f30ab0e42a79a Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Mon, 21 Jun 2021 14:53:08 -0400 Subject: [PATCH 09/24] Incorporating review feedback and making necessary changes --- .../update-tls-certificates.asciidoc | 120 +++++++++++------- 1 file changed, 71 insertions(+), 49 deletions(-) diff --git a/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc b/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc index b777ee39788a9..901089ce84f62 100644 --- a/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc +++ b/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc @@ -1,28 +1,27 @@ [[update-node-certs]] == Updating node security certificates -If your cluster certificates expired or you have a new Certificate Authority -(CA), then you'll need to update the certificates for both the -transport and HTTP layers. When updating your node security certificates, there -are two main scenarios that you'll encounter: +If your cluster certificates are expiring soon or you no longer have the key for +your existing Certificate Authority (CA), then you'll need to update the TLS +certificates for both the transport and HTTP layers. When updating your node +certificates, there are two main scenarios that you'll encounter: -* <> -* <> +* <> +* <> Regardless of the scenario, {es} monitors the SSL resources for updates -on a five-second interval. You can just copy the new certificate and key files -(or keystore) into the {es} configuration directory and your nodes will detect -the changes. +on a five-second interval, which is the default. You can just copy the new +certificate and key files (or keystore) into the {es} configuration directory +and your nodes will detect the changes. Because {es} doesn't reload the `elasticsearch.yml` configuration, you must use *the same file names* so that {es} refreshes the security -certificates and keys. This method of updating certificates is preferred -because it doesn't require a full cluster restart. +certificates and keys. If you need to update the `elasticsearch.yml` configuration or change -certificate passwords that are stored in the -<>, then you must complete a full cluster -restart. {es} will not reload changes for passwords stored in the secure -settings. We recommend <> when restarting your cluster. +passwords for keys or keystores that are stored in the +<>, then you must complete a +<>. {es} will not reload changes for +passwords stored in the secure settings. [[use-rolling-restarts]] .Rolling restarts are preferred @@ -47,10 +46,17 @@ it unable to recover from a network outage or node restart. With the same CA ++++ -If your CA hasn't changed, you can just generate a new certificate, save it with -the same name as your existing certificate, and replace the existing file. -You'll need to generate new certificates and keys for both the transport layer -and the HTTP layer. +If your CA hasn't changed, you can just generate a new node certificate, save it +with the same name as your existing certificate, and replace the existing file. +You'll need to generate new node certificates and keys for both the transport +layer and the HTTP layer. + +[[cert-password-updates]] +IMPORTANT: If your keystore is password protected, the password +is stored in the {es} keystore, _and_ the password needs to change, then you +must perform a <> on your cluster. You +must also use a different file name for the keystore so that {es} reloads the +new file. This procedure assumes that the you have access to the CA certificate and key that was originally generated (or otherwise held by your organization) and used @@ -67,7 +73,8 @@ Create a new PKCS#12 file that contains a certificate and key and replace the existing PKCS#12 file (such as `elastic-certificates.p12`) with the new certificate. -NOTE: The following examples use PKCS#12 files, but the same steps apply to JKS keystores. +NOTE: The following examples use PKCS#12 files, but the same steps apply to JKS +keystores. . Open the `ES_PATH_CONF/elasticsearch.yml` file and check the names of the keystores that are currently in use. You'll use the same names @@ -75,18 +82,17 @@ for your new certificate. + In this example, the keystore and truststore are pointing to different files. Your configuration might use the same file that contains the certificate and CA. +In this case, include the path to that file for both the keystore and truststore. + [source,yaml] ---- xpack.security.transport.ssl.keystore.path: config/elastic-certificates.p12 xpack.security.transport.ssl.keystore.type: PKCS12 -xpack.security.transport.ssl.keystore.password: password -xpack.security.transport.ssl.truststore.path: config/elastic-ca.p12 +xpack.security.transport.ssl.truststore.path: config/elastic-stack-ca.p12 xpack.security.transport.ssl.truststore.type: PKCS12 -xpack.security.transport.ssl.truststore.password: password ---- -. On any node in your cluster, generate a certificate and private key for your +. On every node in your cluster, generate a certificate and private key for your node. You must include the CA that was used to sign the certificate currently in use. + @@ -106,30 +112,33 @@ in use. a. Enter the password for your CA keystore when prompted. b. Enter the name for your keystore, which must match the name of the - keystore currently in use. + keystore currently in use. If your + <>, then save the + keystore with a new filename. c. (Optional) Enter a password for your keystore. -. If you entered a password when creating the node certificate, run the following commands to store the password in the {es} keystore: +. If you entered a password when creating the node certificate, run the +following command to store the password in the {es} keystore: + -- [source,shell] ---- ./bin/elasticsearch-keystore add xpack.security.transport.ssl.keystore.secure_password ---- - -[source,shell] ----- -./bin/elasticsearch-keystore add xpack.security.transport.ssl.truststore.secure_password ----- -- -. [[cert-password-updates]] If your keystore is password protected, the password is stored in the {es} keystore, _and_ the password needs to change, then you must perform a <> on your cluster. Complete the steps until the step that indicates *Perform any needed changes*, and then continue to the next step to replace your existing certificates. - -. Replace your existing certificate with the new certificate, ensuring that the -file names match. +. On every node in your cluster, replace your existing keystore with the new +keystore, ensuring that the file names match. For example, +`elastic-stack-ca.p12`. ++ +IMPORTANT: If your keystore is password protected, the password +is stored in the {es} keystore, _and_ the password needs to change, then you +must update the `ES_PATH_CONF/elasticsearch.yml` file to use the filename of the +new keystore file that you created. -. Repeat the previous step on each node in your cluster to update the existing certificate, completing a rolling restart beforehand if your certificate matches the password stipulations outlined in <>. +. After replacing the keystore on every node in your cluster, restart each node +one at a time. [[node-certs-same-http]] ==== Generate a new certificate for the HTTP layer @@ -221,20 +230,28 @@ certificate to the incoming TLS connections. ./bin/elasticsearch-keystore add xpack.security.http.ssl.keystore.secure_password ---- -. [[cert-password-updates-https]] If your certificate is password protected, the password is stored in the {es} keystore, _and_ the password needs to change, then you must perform a <> on your cluster. Complete the steps until the step that indicates *Perform any needed changes*, and then continue to the next step to replace your existing certificates. +. On every node in your cluster, replace your existing keystore with the new +keystore, ensuring that the file names match. For example, +`http.p12`. ++ +IMPORTANT: If your keystore is password protected, the password +is stored in the {es} keystore, _and_ the password needs to change, then you +must update the `ES_PATH_CONF/elasticsearch.yml` file to use the filename of the +new keystore file that you created. -. Repeat the previous steps on each node in your cluster to update the existing certificate, completing a rolling restart beforehand if your certificate matches the password stipulations outlined in <>. +. After replacing the keystore on every node in your cluster, restart each node +one at a time. [[update-node-certs-different]] === Update security certificates with a different CA ++++ With a different CA ++++ -If your CA needs to change or has already changed, you'll need to generate a new -CA certificate and key. You can then add this CA certificate to your existing CA -truststore so that all nodes in your cluster so know and trust it. Then, -generate a new certificate for each node that are signed by the new CA -certificate and instruct your nodes to use the new files. +If your CA needs to change, you'll need to generate a new CA certificate and key. +You can then add this CA certificate to your existing CA truststore so that all +nodes in your cluster so know and trust it. Then, generate a new certificate for +each node that is signed by the new CA certificate and instruct your nodes to +use the new files. [[node-certs-different-transport]] ==== Generate a new certificate for the transport layer @@ -251,16 +268,14 @@ for your new certificates. + In this example, the keystore and truststore are using different files. Your configuration might use the same file for both the keystore and the -truststore. We recommend using separate files. +truststore. Elastic recommends using separate files. + [source,yaml] ---- xpack.security.transport.ssl.keystore.path: config/elastic-certificates.p12 xpack.security.transport.ssl.keystore.type: PKCS12 -xpack.security.transport.ssl.keystore.password: password xpack.security.transport.ssl.truststore.path: config/elastic-stack-ca.p12 xpack.security.transport.ssl.truststore.type: PKCS12 -xpack.security.transport.ssl.truststore.password: password ---- . On *any* node in your cluster, generate a new CA certificate. You only need @@ -285,7 +300,7 @@ CA certificate in PEM format. certificate and key, or accept the default name of `elastic-stack-ca.zip`. b. Unzip the output file. The resulting directory contains a CA certificate - (`ca.crt`) and private key (`ca.key`). + (`ca.crt`) and a private key (`ca.key`). + -- IMPORTANT: Keep these file in a secure location as they contain the private key @@ -524,6 +539,13 @@ certificate to the incoming TLS connections. ./bin/elasticsearch-keystore add xpack.security.http.ssl.keystore.secure_password ---- -. [[cert-password-update-https]] If your certificate is password protected, the password is stored in the {es} keystore, _and_ the password needs to change, then you must perform a <> on your cluster. Complete the steps until the step that indicates *Perform any needed changes*, and then continue to the next step to replace your existing certificates. +. On every node in your cluster, replace your existing keystore with the new +keystore, ensuring that the file names match. For example, `http.p12`. ++ +IMPORTANT: If your keystore is password protected, the password +is stored in the {es} keystore, _and_ the password needs to change, then you +must update the `ES_PATH_CONF/elasticsearch.yml` file to use the filename of the +new keystore file that you created. -. Repeat the previous steps on each node in your cluster to update the existing certificate, completing a rolling restart beforehand if your certificate matches the password stipulations outlined in <>. +. After replacing the keystore on every node in your cluster, restart each node +one at a time. From 8c101224c82ef8311d03a024ec717b2d2a68725b Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Tue, 22 Jun 2021 16:18:51 -0400 Subject: [PATCH 10/24] Clarifications and changes regarding restarts --- .../update-tls-certificates.asciidoc | 135 ++++++++++-------- 1 file changed, 79 insertions(+), 56 deletions(-) diff --git a/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc b/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc index 901089ce84f62..c9b4f4a938d6a 100644 --- a/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc +++ b/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc @@ -46,10 +46,18 @@ it unable to recover from a network outage or node restart. With the same CA ++++ -If your CA hasn't changed, you can just generate a new node certificate, save it -with the same name as your existing certificate, and replace the existing file. -You'll need to generate new node certificates and keys for both the transport -layer and the HTTP layer. +If your CA hasn't changed, you can replace your existing certificate on each +node with a new certificate that has the same filename. When {es} restarts, it +reloads the file and uses the new certificate. Using the same filename means +that you don't have to update the `elasticsearch.yml` file, and can just +replace the existing certificate. + +You don't have to restart each node, but doing so forces new TLS connections and is <> when updating certificates. +Therefore, the following steps include a node restart after updating each +certificate. + +You'll generate new node certificates and keys for both the transport layer and +the HTTP layer. [[cert-password-updates]] IMPORTANT: If your keystore is password protected, the password @@ -71,14 +79,15 @@ TIP: If your CA has changed, complete the steps in ==== Generate a new certificate for the transport layer Create a new PKCS#12 file that contains a certificate and key and replace the existing PKCS#12 file (such as `elastic-certificates.p12`) with the new -certificate. +certificate. Stop one node at a time, replace the node certificate, and then +restart the node. NOTE: The following examples use PKCS#12 files, but the same steps apply to JKS keystores. . Open the `ES_PATH_CONF/elasticsearch.yml` file and check the names of the -keystores that are currently in use. You'll use the same names -for your new certificate. +keystores that are currently in use. You'll use the same names for your new +certificate. + In this example, the keystore and truststore are pointing to different files. Your configuration might use the same file that contains the certificate and CA. @@ -112,9 +121,11 @@ in use. a. Enter the password for your CA keystore when prompted. b. Enter the name for your keystore, which must match the name of the - keystore currently in use. If your - <>, then save the - keystore with a new filename. + keystore currently in use. ++ +NOTE: If your +<>, then save the +keystore with a new filename. c. (Optional) Enter a password for your keystore. @@ -128,24 +139,32 @@ following command to store the password in the {es} keystore: ---- -- -. On every node in your cluster, replace your existing keystore with the new -keystore, ensuring that the file names match. For example, -`elastic-stack-ca.p12`. -+ -IMPORTANT: If your keystore is password protected, the password -is stored in the {es} keystore, _and_ the password needs to change, then you -must update the `ES_PATH_CONF/elasticsearch.yml` file to use the filename of the -new keystore file that you created. +. Stop {es} on the first node in your cluster where you are updating the +keystore. -. After replacing the keystore on every node in your cluster, restart each node -one at a time. +. Replace your existing keystore with the new keystore, ensuring that the +file names match. For example, `elastic-stack-ca.p12`. + +. If your keystore is password protected, the password is stored in the {es} +keystore, _and_ the password needs to change, then update the +`ES_PATH_CONF/elasticsearch.yml` file to use the filename of the new keystore +file that you created. + +. Restart the node where you updated the keystore. + +. (Optional) Use the <> to verify that +{es} loaded the new keystore. + +. On each additional node in your cluster, stop {es}, update the keystore, +and restart {es}. [[node-certs-same-http]] ==== Generate a new certificate for the HTTP layer -This certificate is used to verify other components when they connect to {es}, -such as {kib} or any of the Elastic language clients. +The certificate for the HTTP layer is used to verify other components when they +connect to {es}, such as {kib} or any of the Elastic language clients. -. Stop {es} and {kib} if they are running. +. Stop {es} and {kib} on the first node in your cluster where you are updating +the HTTP certificate. . From the directory where you installed {es}, run the {es} HTTP certificate tool. @@ -214,14 +233,17 @@ List every hostname and variant used to connect to your cluster over HTTPS. ---- -- -. Rename the `http.p12` file to match the name of your existing certificate for -HTTP client communications. +. If necessary, rename the `http.p12` file to match the name of your existing +certificate for HTTP client communications. This keystore contains both a +certificate and key. -. Replace your existing certificate with the new certificate, ensuring that the -file names match. +. Replace your existing keystore (such as `http.p12`) with the new keystore, +ensuring that the file names match. + -{es} will reload the file and its configuration and start presenting the new -certificate to the incoming TLS connections. +IMPORTANT: If your keystore is password protected, the password +is stored in the {es} keystore, _and_ the password needs to change, then you +must update the `ES_PATH_CONF/elasticsearch.yml` file to use the filename of the +new keystore file that you created. . Add the password for your private key to the secure settings in {es}. + @@ -230,24 +252,22 @@ certificate to the incoming TLS connections. ./bin/elasticsearch-keystore add xpack.security.http.ssl.keystore.secure_password ---- -. On every node in your cluster, replace your existing keystore with the new -keystore, ensuring that the file names match. For example, -`http.p12`. -+ -IMPORTANT: If your keystore is password protected, the password -is stored in the {es} keystore, _and_ the password needs to change, then you -must update the `ES_PATH_CONF/elasticsearch.yml` file to use the filename of the -new keystore file that you created. +. Restart the node where you updated the keystore. {es} will reload the file and +its configuration and start presenting the new certificate to the incoming TLS +connections. + +. (Optional) Use the <> to verify that +{es} loaded the new keystore. -. After replacing the keystore on every node in your cluster, restart each node -one at a time. +. On each additional node in your cluster, stop {es} and {kib}, update the +keystore, and restart {es} and {kib}. [[update-node-certs-different]] === Update security certificates with a different CA ++++ With a different CA ++++ -If your CA needs to change, you'll need to generate a new CA certificate and key. +If your CA is changing, you'll need to generate a new CA certificate and key. You can then add this CA certificate to your existing CA truststore so that all nodes in your cluster so know and trust it. Then, generate a new certificate for each node that is signed by the new CA certificate and instruct your nodes to @@ -452,7 +472,8 @@ You can generate certificates for the HTTP layer using your new CA certificate and private key. This certificate is used to verify other components when they connect to {es}, such as {kib} or any of the Elastic language clients. -. Stop {es} and {kib} if they are running. +. Stop {es} and {kib} on the first node in your cluster where you are updating +the HTTP certificate. . From the directory where you installed {es}, run the {es} HTTP certificate tool. @@ -523,14 +544,17 @@ List every hostname and variant used to connect to your cluster over HTTPS. ---- -- -. Rename the `http.p12` file to match the name of your existing certificate for -HTTP client communications. +. If necessary, rename the `http.p12` file to match the name of your existing +certificate for HTTP client communications. This keystore contains both a +certificate and key. -. Replace your existing certificate with the new certificate, ensuring that the -file names match. +. Replace your existing keystore (such as `http.p12`) with the new keystore, +ensuring that the file names match. + -{es} will reload the file and its configuration and start presenting the new -certificate to the incoming TLS connections. +IMPORTANT: If your keystore is password protected, the password +is stored in the {es} keystore, _and_ the password needs to change, then you +must update the `ES_PATH_CONF/elasticsearch.yml` file to use the filename of the +new keystore file that you created. . Add the password for your private key to the secure settings in {es}. + @@ -539,13 +563,12 @@ certificate to the incoming TLS connections. ./bin/elasticsearch-keystore add xpack.security.http.ssl.keystore.secure_password ---- -. On every node in your cluster, replace your existing keystore with the new -keystore, ensuring that the file names match. For example, `http.p12`. -+ -IMPORTANT: If your keystore is password protected, the password -is stored in the {es} keystore, _and_ the password needs to change, then you -must update the `ES_PATH_CONF/elasticsearch.yml` file to use the filename of the -new keystore file that you created. +. Restart the node where you updated the keystore. {es} will reload the file and +its configuration and start presenting the new certificate to the incoming TLS +connections. + +. (Optional) Use the <> to verify that +{es} loaded the new keystore. -. After replacing the keystore on every node in your cluster, restart each node -one at a time. +. On each additional node in your cluster, stop {es} and {kib}, update the +keystore, and restart {es} and {kib}. \ No newline at end of file From e2438b7b7178fcabc4c753dbf68af6bdd10fe2a5 Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Wed, 23 Jun 2021 09:15:15 -0400 Subject: [PATCH 11/24] Remove errant --pem in basic security setup --- .../securing-communications/security-basic-setup.asciidoc | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/x-pack/docs/en/security/securing-communications/security-basic-setup.asciidoc b/x-pack/docs/en/security/securing-communications/security-basic-setup.asciidoc index 9e5c3abe23c40..49936723af816 100644 --- a/x-pack/docs/en/security/securing-communications/security-basic-setup.asciidoc +++ b/x-pack/docs/en/security/securing-communications/security-basic-setup.asciidoc @@ -89,12 +89,11 @@ generate a CA for your cluster. + [source,shell] ---- -./bin/elasticsearch-certutil cert --ca elastic-stack-ca.p12 --pem +./bin/elasticsearch-certutil cert --ca elastic-stack-ca.p12 ---- + `--ca `:: Name of the CA file used to sign your certificates. The default file name from the `elasticsearch-certutil` tool is `elastic-stack-ca.p12`. - `--pem`:: + a. Enter the password for your CA, or press *Enter* if you did not configure one in the previous step. From ead212de6cfb2a7185074c20e349ebed51d35a0b Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Wed, 23 Jun 2021 09:33:18 -0400 Subject: [PATCH 12/24] Incorporate suggestions from code review Co-authored-by: Ioannis Kakavas --- .../update-tls-certificates.asciidoc | 26 +++++++++---------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc b/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc index c9b4f4a938d6a..09337f2a7611f 100644 --- a/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc +++ b/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc @@ -11,7 +11,7 @@ certificates, there are two main scenarios that you'll encounter: Regardless of the scenario, {es} monitors the SSL resources for updates on a five-second interval, which is the default. You can just copy the new certificate and key files (or keystore) into the {es} configuration directory -and your nodes will detect the changes. +and your nodes will detect the changes and will reload the keys and certificates. Because {es} doesn't reload the `elasticsearch.yml` configuration, you must use *the same file names* so that {es} refreshes the security @@ -61,7 +61,7 @@ the HTTP layer. [[cert-password-updates]] IMPORTANT: If your keystore is password protected, the password -is stored in the {es} keystore, _and_ the password needs to change, then you +is stored in the {es} secure settings, _and_ the password needs to change, then you must perform a <> on your cluster. You must also use a different file name for the keystore so that {es} reloads the new file. @@ -79,8 +79,8 @@ TIP: If your CA has changed, complete the steps in ==== Generate a new certificate for the transport layer Create a new PKCS#12 file that contains a certificate and key and replace the existing PKCS#12 file (such as `elastic-certificates.p12`) with the new -certificate. Stop one node at a time, replace the node certificate, and then -restart the node. +certificate. Stop one node at a time, replace the node keystore, and then +start the node. NOTE: The following examples use PKCS#12 files, but the same steps apply to JKS keystores. @@ -102,7 +102,7 @@ xpack.security.transport.ssl.truststore.type: PKCS12 ---- . On every node in your cluster, generate a certificate and private key for your -node. You must include the CA that was used to sign the certificate currently +node. You must use the CA that was used to sign the certificate currently in use. + [source,shell] @@ -129,7 +129,7 @@ keystore with a new filename. c. (Optional) Enter a password for your keystore. -. If you entered a password when creating the node certificate, run the +. If you entered a password when creating the node keystore, and if it is different than the one the current keystore has, run the following command to store the password in the {es} keystore: + -- @@ -139,7 +139,7 @@ following command to store the password in the {es} keystore: ---- -- -. Stop {es} on the first node in your cluster where you are updating the +. Stop {es} on the current node in your cluster where you are updating the keystore. . Replace your existing keystore with the new keystore, ensuring that the @@ -150,12 +150,12 @@ keystore, _and_ the password needs to change, then update the `ES_PATH_CONF/elasticsearch.yml` file to use the filename of the new keystore file that you created. -. Restart the node where you updated the keystore. +. Start the node where you updated the keystore. . (Optional) Use the <> to verify that {es} loaded the new keystore. -. On each additional node in your cluster, stop {es}, update the keystore, +. On each additional node in your cluster, perform the previous steps, and restart {es}. [[node-certs-same-http]] @@ -346,7 +346,7 @@ keytool -importcert -trustcacerts -noprompt -keystore elastic-stack-ca.p12 \ `-storepass`:: Password for the CA truststore. - `-alias`:: Name that you want to assign to the new CA certificate. + `-alias`:: Name that you want to assign to the new CA certificate entry in the keystore. `-file`:: Name of the new CA certificate to import. ==== @@ -454,7 +454,7 @@ in your cluster. Include the `instances.yml` file that you created previously. d. Rename the `.p12` file to match the existing file name specified by the `xpack.security.transport.ssl.keystore.path` variable in - the `elasticsearch.yml` file. + the `elasticsearch.yml` file on each node. . On *every* node, copy the appropriate node certificate to the `ES_PATH_CONF` directory. @@ -464,7 +464,7 @@ configuration files. If you installed {es} using archive distributions (`zip` or `tar.gz`), the variable defaults to `ES_HOME/config`. If you used package distributions (Debian or RPM), the variable defaults to `/etc/elasticsearch`. -. Delete the old node certificate from each node. +. Delete the old node keystore from each node. [[node-certs-different-http]] ==== Generate a new certificate for the HTTP layer @@ -571,4 +571,4 @@ connections. {es} loaded the new keystore. . On each additional node in your cluster, stop {es} and {kib}, update the -keystore, and restart {es} and {kib}. \ No newline at end of file +keystore, and restart {es} and {kib}. From 76b2be3842043268a5e6eb3f8bc217e4c5259cb9 Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Wed, 23 Jun 2021 15:32:31 -0400 Subject: [PATCH 13/24] Many, many updates. But good ones. --- .../update-tls-certificates.asciidoc | 349 ++++++++++++------ 1 file changed, 231 insertions(+), 118 deletions(-) diff --git a/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc b/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc index 09337f2a7611f..057e3a803718f 100644 --- a/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc +++ b/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc @@ -1,17 +1,23 @@ [[update-node-certs]] == Updating node security certificates -If your cluster certificates are expiring soon or you no longer have the key for -your existing Certificate Authority (CA), then you'll need to update the TLS -certificates for both the transport and HTTP layers. When updating your node -certificates, there are two main scenarios that you'll encounter: +You need to update your TLS certificates if your current node certificates might +expire soon, you're adding new nodes to your secured cluster, or security +breach has broken the trust of your certificate chain. In these instances where +<>, you can sign new +certificates using the original Certificate Authority (CA) that you used to sign your existing certificates. -* <> -* <> +If you have to trust a new CA, you need to +<> for each +node that is signed by the new CA certificate and instruct your nodes to trust +this certificate chain. + +Depending on which certificates are expiring, you might need to update the +certificates for the transport layer, the HTTP layer, or both. Regardless of the scenario, {es} monitors the SSL resources for updates on a five-second interval, which is the default. You can just copy the new certificate and key files (or keystore) into the {es} configuration directory -and your nodes will detect the changes and will reload the keys and certificates. +and your nodes will detect the changes and reload the keys and certificates. Because {es} doesn't reload the `elasticsearch.yml` configuration, you must use *the same file names* so that {es} refreshes the security @@ -46,45 +52,46 @@ it unable to recover from a network outage or node restart. With the same CA ++++ -If your CA hasn't changed, you can replace your existing certificate on each -node with a new certificate that has the same filename. When {es} restarts, it -reloads the file and uses the new certificate. Using the same filename means -that you don't have to update the `elasticsearch.yml` file, and can just -replace the existing certificate. +This procedure assumes that the you have access to the CA certificate and key +that was originally generated (or otherwise held by your organization) and used +to sign the certificate that is currently in use. It also assumes that the +clients connecting to {es} on the HTTP layer are configured to trust the CA +certificate. + +If you have access to the CA used to sign your existing certificates, you only +need to replace the certificates and keys for each node in your cluster. If you +replace your existing certificates and keys on each node use the same filenames, +{es} reloads the files starts using the new certificates and keys. You don't have to restart each node, but doing so forces new TLS connections and is <> when updating certificates. Therefore, the following steps include a node restart after updating each certificate. -You'll generate new node certificates and keys for both the transport layer and -the HTTP layer. +The following steps provide instructions for generating new node certificates +and keys for both the transport layer and the HTTP layer. You might only need +to replace one of these layer's certificates depending on which of your +certificates are expiring. [[cert-password-updates]] IMPORTANT: If your keystore is password protected, the password -is stored in the {es} secure settings, _and_ the password needs to change, then you -must perform a <> on your cluster. You -must also use a different file name for the keystore so that {es} reloads the -new file. - -This procedure assumes that the you have access to the CA certificate and key -that was originally generated (or otherwise held by your organization) and used -to sign the certificate that is currently in use. It also assumes that the -clients connecting to {es} on the HTTP layer are configured to trust the CA -certificate. +is stored in the {es} secure settings, _and_ the password needs to change, then +you must perform a <> on your cluster. +You must also use a different file name for the keystore so that {es} doesn't +reload the file before the node is restarted. TIP: If your CA has changed, complete the steps in <>. [[node-certs-same-transport]] ==== Generate a new certificate for the transport layer -Create a new PKCS#12 file that contains a certificate and key and replace -the existing PKCS#12 file (such as `elastic-certificates.p12`) with the new -certificate. Stop one node at a time, replace the node keystore, and then -start the node. - -NOTE: The following examples use PKCS#12 files, but the same steps apply to JKS +The following examples use PKCS#12 files, but the same steps apply to JKS keystores. +Rather than run the `elasticsearch-certutil` tool once for each node, create an +`instances.yml` file that contains information about each of your nodes. You can +then use the `elasticsearch-certutil` tool to generate certificates for all of +your nodes with a single command. + . Open the `ES_PATH_CONF/elasticsearch.yml` file and check the names of the keystores that are currently in use. You'll use the same names for your new certificate. @@ -101,36 +108,73 @@ xpack.security.transport.ssl.truststore.path: config/elastic-stack-ca.p12 xpack.security.transport.ssl.truststore.type: PKCS12 ---- -. On every node in your cluster, generate a certificate and private key for your -node. You must use the CA that was used to sign the certificate currently -in use. +. On any node in your cluster, create an `instances.yml` file that contains +information about each of your nodes. Include all IP addresses and DNS names +that you use to identify each node. ++ +[source,yaml] +---- +instances: + - name: "node1" + ip: + - "192.168.1.101" + dns: + - "node1" + - "node1.mydomain.com" + - name: "node2" + ip: + - "192.168.1.102" + dns: + - "node2" + - "node2.mydomain.com" + - name: "node3" + ip: + - "192.168.1.103" + dns: + - "node3" + - "node3.mydomain.com" + - name: "node4" + ip: + - "192.168.1.104" + dns: + - "node4" + - "node4.mydomain.com" +---- + +. Using your existing CA, generate a keystore for each of your nodes. You must +use the CA that was used to sign the certificate currently in use. + [source,shell] ---- -./bin/elasticsearch-certutil cert --ca elastic-stack-ca.p12 +./bin/elasticsearch-certutil cert --in instances.yml --ca elastic-stack-ca.p12 ---- + [%collapsible%open] .Command parameters ==== - `--ca `:: Name of the CA keystore used to sign your certificates. The - default file name from the `elasticsearch-certutil` tool is - `elastic-stack-ca.p12`. + `-in`:: Specifies the name of the input YAML file (`instances.yml`) + containing information about each of your nodes. + + `--ca `:: Name of the CA keystore used to sign your certificates. ==== -+ - a. Enter the password for your CA keystore when prompted. - b. Enter the name for your keystore, which must match the name of the - keystore currently in use. -+ -NOTE: If your -<>, then save the -keystore with a new filename. + a. Enter a name for the output file or accept the default of + `certificate-bundle.zip`. - c. (Optional) Enter a password for your keystore. + b. When prompted, enter a password for each node certificate. It's good + practice to use a different password for each node certificate and store the + files in a secure location. + + c. Decompress the `certificate-bundle.zip` file. The output contains a + directory for each of your nodes with a `.p12` file. -. If you entered a password when creating the node keystore, and if it is different than the one the current keystore has, run the -following command to store the password in the {es} keystore: + d. Rename the `.p12` file to match the existing file name + specified by the `xpack.security.transport.ssl.keystore.path` variable in + the `elasticsearch.yml` file on each node. + +. If you entered a password when creating the node keystore that is different +from the current keystore password, run the following command to store the +password in the {es} keystore: + -- [source,shell] @@ -142,29 +186,50 @@ following command to store the password in the {es} keystore: . Stop {es} on the current node in your cluster where you are updating the keystore. +[[replace-keystores]] . Replace your existing keystore with the new keystore, ensuring that the -file names match. For example, `elastic-stack-ca.p12`. +file names match. For example, `node1.p12`. ++ +If your +<>, then save the +keystore with a new filename so that {es} doesn't attempt to reload the file +before you update the password. -. If your keystore is password protected, the password is stored in the {es} -keystore, _and_ the password needs to change, then update the -`ES_PATH_CONF/elasticsearch.yml` file to use the filename of the new keystore -file that you created. +. If you needed to save the new keystore with a new filename, update the +`ES_PATH_CONF/elasticsearch.yml` file to use the filename of the new keystore. +For example: ++ +[source,yaml] +---- +xpack.security.transport.ssl.keystore.path: config/node1.p12 +xpack.security.transport.ssl.keystore.type: PKCS12 +xpack.security.transport.ssl.truststore.path: config/elastic-stack-ca.p12 +xpack.security.transport.ssl.truststore.type: PKCS12 +---- . Start the node where you updated the keystore. . (Optional) Use the <> to verify that {es} loaded the new keystore. -. On each additional node in your cluster, perform the previous steps, -and restart {es}. +. One at a time, stop {es} on each additional node in your cluster. + +. Complete the previous steps on each additional node, starting with the step +for <>. [[node-certs-same-http]] ==== Generate a new certificate for the HTTP layer -The certificate for the HTTP layer is used to verify other components when they -connect to {es}, such as {kib} or any of the Elastic language clients. +Other components such as {kib} or any of the Elastic language clients verify +this certificate when they connect to {es}. + +NOTE: If your organization has its own CA, you'll need to +<>. CSRs contain +information that your CA uses to generate and sign a security certificate +instead of using self-signed certificates that the `elasticsearch-certutil` tool +generates. -. Stop {es} and {kib} on the first node in your cluster where you are updating -the HTTP certificate. +. Stop {es} on the current node in your cluster where you are updating the HTTP +certificate. . From the directory where you installed {es}, run the {es} HTTP certificate tool. @@ -188,8 +253,8 @@ explaining how to use these files. d. Enter the password for your CA. e. Enter an expiration value for your certificate. You can enter the - validity period in years, months, or days. For example, enter `90D` for 90 - days. + validity period in years, months, or days. For example, enter `1y` for one + year. f. When asked if you want to generate one certificate per node, enter `y`. + @@ -213,23 +278,31 @@ List every hostname and variant used to connect to your cluster over HTTPS. your private key when prompted. . Unzip the generated `elasticsearch-ssl-http.zip` file. This compressed file - contains one directory for both {es} and {kib}. + contains one directory for both {es} and {kib}. Within the `/elasticsearch` + directory is a directory for each node that you specified with it's own + `http.p12` file. + -- [source,txt] ---- -/elasticsearch +/node1 |_ README.txt |_ http.p12 |_ sample-elasticsearch.yml ---- -[source,txt] ---- -/kibana +/node2 |_ README.txt -|_ elasticsearch-ca.pem -|_ sample-kibana.yml +|_ http.p12 +|_ sample-elasticsearch.yml +---- + +---- +/node3 +|_ README.txt +|_ http.p12 +|_ sample-elasticsearch.yml ---- -- @@ -240,12 +313,23 @@ certificate and key. . Replace your existing keystore (such as `http.p12`) with the new keystore, ensuring that the file names match. + -IMPORTANT: If your keystore is password protected, the password -is stored in the {es} keystore, _and_ the password needs to change, then you -must update the `ES_PATH_CONF/elasticsearch.yml` file to use the filename of the -new keystore file that you created. +If your +<>, then save the +keystore with a new filename so that {es} doesn't attempt to reload the file +before you update the password. -. Add the password for your private key to the secure settings in {es}. +. If you needed to save the new keystore with a new filename, update the +`ES_PATH_CONF/elasticsearch.yml` file to use the filename of the new keystore. +For example: ++ +[source,yaml] +---- +xpack.security.http.ssl.enabled: true +xpack.security.http.ssl.keystore.path: new-http.p12 +---- + +. If your keystore password is changing, add the password for your private key +to the secure settings in {es}. + [source,shell] ---- @@ -259,19 +343,17 @@ connections. . (Optional) Use the <> to verify that {es} loaded the new keystore. -. On each additional node in your cluster, stop {es} and {kib}, update the -keystore, and restart {es} and {kib}. +. On each additional node in your cluster, stop {es}, update the keystore, and +restart {es}. [[update-node-certs-different]] === Update security certificates with a different CA ++++ With a different CA ++++ -If your CA is changing, you'll need to generate a new CA certificate and key. -You can then add this CA certificate to your existing CA truststore so that all -nodes in your cluster so know and trust it. Then, generate a new certificate for -each node that is signed by the new CA certificate and instruct your nodes to -use the new files. +If you have to trust a new CA, generate a new CA certificate and key for each +node that is signed by the new CA certificate and instruct your nodes to trust +this certificate chain. [[node-certs-different-transport]] ==== Generate a new certificate for the transport layer @@ -301,8 +383,11 @@ xpack.security.transport.ssl.truststore.type: PKCS12 . On *any* node in your cluster, generate a new CA certificate. You only need to complete this step one time. + -NOTE: If your organization has its own CA, then use that CA to generate a new -CA certificate in PEM format. +NOTE: If your organization has its own CA, you'll need to +<>. CSRs contain +information that your CA uses to generate and sign a security certificate +instead of using self-signed certificates that the `elasticsearch-certutil` tool +generates. + [source,shell] ---- @@ -359,24 +444,9 @@ When prompted, enter the password for the CA truststore. + [source,shell] ---- -openssl pkcs12 -info -in config/elastic-stack-ca.p12 +keytool -keystore config/elastic-stack-ca.p12 -list ---- -. (Optional) Remove the old CA certificate from your truststore. -+ -[source,shell] ----- -keytool -delete -noprompt -alias old-ca -keystore config/elastic-stack-ca.p12 \ --storepass ----- -+ -[%collapsible%open] -.Command parameters -==== - `-alias`:: Name of the old CA certificate that you want to remove from your - truststore. -==== - [discrete] [[node-certs-different-nodes]] ==== Generate a new certificate for each node in your cluster @@ -469,11 +539,17 @@ package distributions (Debian or RPM), the variable defaults to `/etc/elasticsea [[node-certs-different-http]] ==== Generate a new certificate for the HTTP layer You can generate certificates for the HTTP layer using your new CA certificate -and private key. This certificate is used to verify other components when they -connect to {es}, such as {kib} or any of the Elastic language clients. +and private key. Other components such as {kib} or any of the Elastic language +clients verify this certificate when they connect to {es}. + +NOTE: If your organization has its own CA, you'll need to +<>. CSRs contain +information that your CA uses to generate and sign a security certificate +instead of using self-signed certificates that the `elasticsearch-certutil` tool +generates. -. Stop {es} and {kib} on the first node in your cluster where you are updating -the HTTP certificate. +. Stop {es} on the first node in your cluster where you are updating the HTTP +certificate. . From the directory where you installed {es}, run the {es} HTTP certificate tool. @@ -498,8 +574,8 @@ explaining how to use these files. the path to the `ca.key` file. e. Enter an expiration value for your certificate. You can enter the - validity period in years, months, or days. For example, enter `90D` for 90 - days. + validity period in years, months, or days. For example, enter `1y` for one + year. f. When asked if you want to generate one certificate per node, enter `y`. + @@ -523,40 +599,59 @@ List every hostname and variant used to connect to your cluster over HTTPS. your keystore when prompted. . Unzip the generated `elasticsearch-ssl-http.zip` file. This compressed file - contains one directory for both {es} and {kib}. Additionally, a directory is - created for each node that you specified with it's own `http.p12` file. + contains one directory for both {es} and {kib}. Within the `/elasticsearch` + directory is a directory for each node that you specified with it's own + `http.p12` file. + -- [source,txt] ---- -/elasticsearch +/node1 +|_ README.txt +|_ http.p12 +|_ sample-elasticsearch.yml +---- + +---- +/node2 |_ README.txt |_ http.p12 |_ sample-elasticsearch.yml ---- -[source,txt] ---- -/kibana +/node3 |_ README.txt -|_ elasticsearch-ca.pem -|_ sample-kibana.yml +|_ http.p12 +|_ sample-elasticsearch.yml ---- -- -. If necessary, rename the `http.p12` file to match the name of your existing +. If necessary, rename each `http.p12` file to match the name of your existing certificate for HTTP client communications. This keystore contains both a certificate and key. +[[replace-keystore-files]] . Replace your existing keystore (such as `http.p12`) with the new keystore, ensuring that the file names match. + -IMPORTANT: If your keystore is password protected, the password -is stored in the {es} keystore, _and_ the password needs to change, then you -must update the `ES_PATH_CONF/elasticsearch.yml` file to use the filename of the -new keystore file that you created. +If your +<>, then save the +keystore with a new filename so that {es} doesn't attempt to reload the file +before you update the password. -. Add the password for your private key to the secure settings in {es}. +. If you needed to save the new keystore with a new filename, update the +`ES_PATH_CONF/elasticsearch.yml` file to use the filename of the new keystore. +For example: ++ +[source,yaml] +---- +xpack.security.http.ssl.enabled: true +xpack.security.http.ssl.keystore.path: new-http.p12 +---- + +. If your keystore password is changing, add the password for your private key +to the secure settings in {es}. + [source,shell] ---- @@ -570,5 +665,23 @@ connections. . (Optional) Use the <> to verify that {es} loaded the new keystore. -. On each additional node in your cluster, stop {es} and {kib}, update the -keystore, and restart {es} and {kib}. +. One at a time, stop {es} on each additional node in your cluster. + +. Complete the previous steps on each additional node, starting with the step +for <>. + +. (Optional) After rotating keystores on each node in your cluster, remove the +old CA certificate from your truststore. ++ +[source,shell] +---- +keytool -delete -noprompt -alias old-ca -keystore config/elastic-stack-ca.p12 \ +-storepass +---- ++ +[%collapsible%open] +.Command parameters +==== + `-alias`:: Name of the old CA certificate that you want to remove from your + truststore. +==== From 286a2d873bd88cb032950034644fb4e7d21e360f Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Thu, 24 Jun 2021 07:31:23 -0400 Subject: [PATCH 14/24] Add languages for snippets --- .../securing-communications/update-tls-certificates.asciidoc | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc b/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc index 057e3a803718f..0fc55bbd76542 100644 --- a/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc +++ b/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc @@ -291,6 +291,7 @@ List every hostname and variant used to connect to your cluster over HTTPS. |_ sample-elasticsearch.yml ---- +[source,txt] ---- /node2 |_ README.txt @@ -298,6 +299,7 @@ List every hostname and variant used to connect to your cluster over HTTPS. |_ sample-elasticsearch.yml ---- +[source,txt] ---- /node3 |_ README.txt @@ -612,6 +614,7 @@ List every hostname and variant used to connect to your cluster over HTTPS. |_ sample-elasticsearch.yml ---- +[source,txt] ---- /node2 |_ README.txt @@ -619,6 +622,7 @@ List every hostname and variant used to connect to your cluster over HTTPS. |_ sample-elasticsearch.yml ---- +[source,txt] ---- /node3 |_ README.txt From c82ffdb82049d4dd5a25c8a12bb9839220e62e58 Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Thu, 24 Jun 2021 15:46:11 -0400 Subject: [PATCH 15/24] Reorder steps to reference rolling restart throughout for consistency --- .../update-tls-certificates.asciidoc | 128 +++++++++++------- 1 file changed, 78 insertions(+), 50 deletions(-) diff --git a/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc b/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc index 0fc55bbd76542..332702fa54f97 100644 --- a/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc +++ b/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc @@ -183,11 +183,13 @@ password in the {es} keystore: ---- -- -. Stop {es} on the current node in your cluster where you are updating the -keystore. +. [[start-rolling-restart,step 5]]On the current node in your cluster where you're updating the keystore, +start a <>. ++ +Stop at the step indicating *Perform any needed changes*, and then proceed to +the next step in this procedure. -[[replace-keystores]] -. Replace your existing keystore with the new keystore, ensuring that the +. [[replace-keystores]]Replace your existing keystore with the new keystore, ensuring that the file names match. For example, `node1.p12`. + If your @@ -207,15 +209,14 @@ xpack.security.transport.ssl.truststore.path: config/elastic-stack-ca.p12 xpack.security.transport.ssl.truststore.type: PKCS12 ---- -. Start the node where you updated the keystore. +. Start the node where you updated the keystore, and then complete the remaining +steps for a <>. -. (Optional) Use the <> to verify that +. [[verify-keystore,step 9]](Optional) Use the <> to verify that {es} loaded the new keystore. -. One at a time, stop {es} on each additional node in your cluster. - -. Complete the previous steps on each additional node, starting with the step -for <>. +. One node at a time, complete <> through +<> until you've updated all keystores in your cluster. [[node-certs-same-http]] ==== Generate a new certificate for the HTTP layer @@ -228,11 +229,8 @@ information that your CA uses to generate and sign a security certificate instead of using self-signed certificates that the `elasticsearch-certutil` tool generates. -. Stop {es} on the current node in your cluster where you are updating the HTTP -certificate. - -. From the directory where you installed {es}, run the {es} HTTP certificate -tool. +. On any node in your cluster where {es} is installed, run the {es} HTTP +certificate tool. + [source,shell] ---- @@ -280,7 +278,7 @@ List every hostname and variant used to connect to your cluster over HTTPS. . Unzip the generated `elasticsearch-ssl-http.zip` file. This compressed file contains one directory for both {es} and {kib}. Within the `/elasticsearch` directory is a directory for each node that you specified with it's own - `http.p12` file. + `http.p12` file. For example: + -- [source,txt] @@ -312,8 +310,14 @@ List every hostname and variant used to connect to your cluster over HTTPS. certificate for HTTP client communications. This keystore contains both a certificate and key. -. Replace your existing keystore (such as `http.p12`) with the new keystore, -ensuring that the file names match. +. [[start-rolling-restart-http,step 5]]On the current node in your cluster where you're updating the keystore, +start a <>. ++ +Stop at the step indicating *Perform any needed changes*, and then proceed to +the next step in this procedure. + +. Replace your existing keystore with the new keystore, ensuring that the +file names match. For example, `node1-http.p12`. + If your <>, then save the @@ -327,7 +331,7 @@ For example: [source,yaml] ---- xpack.security.http.ssl.enabled: true -xpack.security.http.ssl.keystore.path: new-http.p12 +xpack.security.http.ssl.keystore.path: node1-http.p12 ---- . If your keystore password is changing, add the password for your private key @@ -338,15 +342,14 @@ to the secure settings in {es}. ./bin/elasticsearch-keystore add xpack.security.http.ssl.keystore.secure_password ---- -. Restart the node where you updated the keystore. {es} will reload the file and -its configuration and start presenting the new certificate to the incoming TLS -connections. +. Start the node where you updated the keystore, and then complete the remaining +steps for a <>. -. (Optional) Use the <> to verify that +. [[verify-keystore-http,step 10]](Optional) Use the <> to verify that {es} loaded the new keystore. -. On each additional node in your cluster, stop {es}, update the keystore, and -restart {es}. +. One node at a time, complete <> through +<> until you've updated all keystores in your cluster. [[update-node-certs-different]] === Update security certificates with a different CA @@ -528,15 +531,41 @@ in your cluster. Include the `instances.yml` file that you created previously. specified by the `xpack.security.transport.ssl.keystore.path` variable in the `elasticsearch.yml` file on each node. -. On *every* node, copy the appropriate node certificate to the `ES_PATH_CONF` -directory. +. [[start-rolling-restart-newca,step 3]]On the current node in your cluster where +you're updating the keystore, start a +<>. ++ +Stop at the step indicating *Perform any needed changes*, and then proceed to +the next step in this procedure. + +. Replace your existing keystore with the new keystore, ensuring that the +file names match. For example, `.p12`. ++ +If your +<>, then save the +keystore with a new filename so that {es} doesn't attempt to reload the file +before you update the password. + +. If you needed to save the new keystore with a new filename, update the +`ES_PATH_CONF/elasticsearch.yml` file to use the filename of the new keystore. +For example: + -NOTE: The `ES_PATH_CONF` variable is the path for the {es} -configuration files. If you installed {es} using archive distributions -(`zip` or `tar.gz`), the variable defaults to `ES_HOME/config`. If you used -package distributions (Debian or RPM), the variable defaults to `/etc/elasticsearch`. +[source,yaml] +---- +xpack.security.transport.ssl.keystore.path: config/.p12 +xpack.security.transport.ssl.keystore.type: PKCS12 +xpack.security.transport.ssl.truststore.path: config/elastic-stack-ca.p12 +xpack.security.transport.ssl.truststore.type: PKCS12 +---- -. Delete the old node keystore from each node. +. Start the node where you updated the keystore, and then complete the remaining +steps for a <>. + +. [[verify-keystore-newca,step 7]](Optional) Use the <> to verify that +{es} loaded the new keystore. + +. One node at a time, complete <> through +<> until you've updated all keystores in your cluster. [[node-certs-different-http]] ==== Generate a new certificate for the HTTP layer @@ -550,11 +579,8 @@ information that your CA uses to generate and sign a security certificate instead of using self-signed certificates that the `elasticsearch-certutil` tool generates. -. Stop {es} on the first node in your cluster where you are updating the HTTP -certificate. - -. From the directory where you installed {es}, run the {es} HTTP certificate -tool. +. On any node in your cluster where {es} is installed, run the {es} HTTP +certificate tool. + [source,shell] ---- @@ -603,7 +629,7 @@ List every hostname and variant used to connect to your cluster over HTTPS. . Unzip the generated `elasticsearch-ssl-http.zip` file. This compressed file contains one directory for both {es} and {kib}. Within the `/elasticsearch` directory is a directory for each node that you specified with it's own - `http.p12` file. + `http.p12` file. For example: + -- [source,txt] @@ -635,9 +661,14 @@ List every hostname and variant used to connect to your cluster over HTTPS. certificate for HTTP client communications. This keystore contains both a certificate and key. -[[replace-keystore-files]] -. Replace your existing keystore (such as `http.p12`) with the new keystore, -ensuring that the file names match. +. [[start-rolling-restart-http-newca,step 5]]On the current node in your cluster where you're updating the keystore, +start a <>. ++ +Stop at the step indicating *Perform any needed changes*, and then proceed to +the next step in this procedure. + +. Replace your existing keystore with the new keystore, ensuring that the +file names match. For example, `node1-http.p12`. + If your <>, then save the @@ -651,7 +682,7 @@ For example: [source,yaml] ---- xpack.security.http.ssl.enabled: true -xpack.security.http.ssl.keystore.path: new-http.p12 +xpack.security.http.ssl.keystore.path: node1-http.p12 ---- . If your keystore password is changing, add the password for your private key @@ -662,17 +693,14 @@ to the secure settings in {es}. ./bin/elasticsearch-keystore add xpack.security.http.ssl.keystore.secure_password ---- -. Restart the node where you updated the keystore. {es} will reload the file and -its configuration and start presenting the new certificate to the incoming TLS -connections. +. Start the node where you updated the keystore, and then complete the remaining +steps for a <>. -. (Optional) Use the <> to verify that +. [[verify-keystore-http-newca,step 10]](Optional) Use the <> to verify that {es} loaded the new keystore. -. One at a time, stop {es} on each additional node in your cluster. - -. Complete the previous steps on each additional node, starting with the step -for <>. +. One node at a time, complete <> through +<> until you've updated all keystores in your cluster. . (Optional) After rotating keystores on each node in your cluster, remove the old CA certificate from your truststore. From 8c48acf5ff590cc48b323e72d502cbb21dad82d8 Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Mon, 28 Jun 2021 13:59:05 -0400 Subject: [PATCH 16/24] Add clarifying what's next steps --- .../update-tls-certificates.asciidoc | 34 ++++++++++++++++++- 1 file changed, 33 insertions(+), 1 deletion(-) diff --git a/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc b/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc index 332702fa54f97..7df7cc31b0bfe 100644 --- a/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc +++ b/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc @@ -218,6 +218,14 @@ steps for a <>. . One node at a time, complete <> through <> until you've updated all keystores in your cluster. +[discrete] +[[transport-layer-sameca-whatsnext]] +==== What's next? +Well done! You've updated the keystore for the transport layer. You can also +<> if +necessary. If you're not updating the keystore for the HTTP layer, then you're +all set. + [[node-certs-same-http]] ==== Generate a new certificate for the HTTP layer Other components such as {kib} or any of the Elastic language clients verify @@ -567,6 +575,30 @@ steps for a <>. . One node at a time, complete <> through <> until you've updated all keystores in your cluster. +. (Optional) After rotating keystores on each node in your cluster, remove the +old CA certificate from your truststore. ++ +[source,shell] +---- +keytool -delete -noprompt -alias -keystore config/elastic-stack-ca.p12 \ +-storepass +---- ++ +[%collapsible%open] +.Command parameters +==== + `-alias`:: Name of the old CA certificate that you want to remove from your + truststore. +==== + +[discrete] +[[transport-layer-newca-whatsnext]] +==== What's next? +Well done! You've updated the keystore for the transport layer. You can also +<> if +necessary. If you're not updating the keystore for the HTTP layer, then you're +all set. + [[node-certs-different-http]] ==== Generate a new certificate for the HTTP layer You can generate certificates for the HTTP layer using your new CA certificate @@ -707,7 +739,7 @@ old CA certificate from your truststore. + [source,shell] ---- -keytool -delete -noprompt -alias old-ca -keystore config/elastic-stack-ca.p12 \ +keytool -delete -noprompt -alias -keystore config/http.p12 \ -storepass ---- + From c855d0e8fb195f51037d685fab4535f200c23363 Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Mon, 28 Jun 2021 16:29:14 -0400 Subject: [PATCH 17/24] Add instructions for updating Kibana certificate --- .../update-tls-certificates.asciidoc | 33 +++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc b/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc index 7df7cc31b0bfe..ac471445c949e 100644 --- a/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc +++ b/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc @@ -749,3 +749,36 @@ keytool -delete -noprompt -alias -keystore config/http.p12 \ `-alias`:: Name of the old CA certificate that you want to remove from your truststore. ==== + +[discrete] +[[http-kibana-newca-whatsnext]] +==== What's next? +Well done! You've updated the keystore for the HTTP layer. You can now +<>. + +[[node-certs-different-kibana]] +==== Update encryption between {kib} and {es} + +When you ran the `elasticsearch-certutil` tool with the `http` option, it +created a `/kibana` directory containing an `elasticsearch-ca.pem` file. You +use this file to configure {kib} to trust the {es} CA for the HTTP +layer. + +. Copy the `elasticsearch-ca.pem` file to the {kib} configuration directory, +as defined by the `KBN_PATH_CONF` path. ++ +NOTE: `KBN_PATH_CONF` contains the path for the {kib} configuration files. If +you installed {kib} using archive distributions (`zip` or `tar.gz`), the +path defaults to `KBN_HOME/config`. If you used package distributions +(Debian or RPM), the path defaults to `/etc/kibana`. + +. If you modified the filename for the `elasticsearch-ca.pem` file, edit +`kibana.yml` and update the configuration to specify the location of the +security certificate for the HTTP layer. ++ +[source,yaml] +---- +elasticsearch.ssl.certificateAuthorities: KBN_PATH_CONF/elasticsearch-ca.pem +---- + +. Restart {kib}. \ No newline at end of file From 271d8bf96c1c8ca31a1df15bf2607fa7a0f3a7c1 Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Thu, 8 Jul 2021 17:09:22 -0400 Subject: [PATCH 18/24] Apply suggestions from Ioannis' stellar code review Co-authored-by: Ioannis Kakavas --- .../update-tls-certificates.asciidoc | 31 +++++++++---------- 1 file changed, 14 insertions(+), 17 deletions(-) diff --git a/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc b/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc index ac471445c949e..7c10bed163223 100644 --- a/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc +++ b/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc @@ -1,12 +1,12 @@ [[update-node-certs]] == Updating node security certificates You need to update your TLS certificates if your current node certificates might -expire soon, you're adding new nodes to your secured cluster, or security +expire soon, you're adding new nodes to your secured cluster, or a security breach has broken the trust of your certificate chain. In these instances where <>, you can sign new certificates using the original Certificate Authority (CA) that you used to sign your existing certificates. -If you have to trust a new CA, you need to +If you have to trust a new CA from your organization, or you need to generate a new CA yourself, you need to use this new CA to sign the new node certificates and instruct your nodes to trust the new CA. <> for each node that is signed by the new CA certificate and instruct your nodes to trust this certificate chain. @@ -15,18 +15,18 @@ Depending on which certificates are expiring, you might need to update the certificates for the transport layer, the HTTP layer, or both. Regardless of the scenario, {es} monitors the SSL resources for updates -on a five-second interval, which is the default. You can just copy the new +on a five-second interval by default. You can just copy the new certificate and key files (or keystore) into the {es} configuration directory and your nodes will detect the changes and reload the keys and certificates. Because {es} doesn't reload the `elasticsearch.yml` configuration, -you must use *the same file names* so that {es} refreshes the security +you must use *the same file names* so that {es} refreshes the certificates and keys. If you need to update the `elasticsearch.yml` configuration or change passwords for keys or keystores that are stored in the <>, then you must complete a -<>. {es} will not reload changes for +<>. {es} will not automatically reload changes for passwords stored in the secure settings. [[use-rolling-restarts]] @@ -47,14 +47,14 @@ it unable to recover from a network outage or node restart. **** [[update-node-certs-same]] -=== Update security certificates with the same CA +=== Update certificates with the same CA ++++ With the same CA ++++ This procedure assumes that the you have access to the CA certificate and key that was originally generated (or otherwise held by your organization) and used -to sign the certificate that is currently in use. It also assumes that the +to sign the node certificates currently in use. It also assumes that the clients connecting to {es} on the HTTP layer are configured to trust the CA certificate. @@ -233,7 +233,7 @@ this certificate when they connect to {es}. NOTE: If your organization has its own CA, you'll need to <>. CSRs contain -information that your CA uses to generate and sign a security certificate +information that your CA uses to generate and sign a certificate instead of using self-signed certificates that the `elasticsearch-certutil` tool generates. @@ -315,8 +315,7 @@ List every hostname and variant used to connect to your cluster over HTTPS. -- . If necessary, rename the `http.p12` file to match the name of your existing -certificate for HTTP client communications. This keystore contains both a -certificate and key. +certificate for HTTP client communications. . [[start-rolling-restart-http,step 5]]On the current node in your cluster where you're updating the keystore, start a <>. @@ -364,9 +363,7 @@ steps for a <>. ++++ With a different CA ++++ -If you have to trust a new CA, generate a new CA certificate and key for each -node that is signed by the new CA certificate and instruct your nodes to trust -this certificate chain. +If you have to trust a new CA from your organization, or you need to generate a new CA yourself, use this new CA to sign the new node certificates and instruct your nodes to trust the new CA. [[node-certs-different-transport]] ==== Generate a new certificate for the transport layer @@ -378,8 +375,8 @@ NOTE: The following examples use PKCS#12 files, but the same steps apply to JKS keystores. . Open the `ES_PATH_CONF/elasticsearch.yml` file and check the names of the -security certificates that are currently in use. You'll use the same names -for your new certificates. +keystores that are currently in use. You'll use the same names +for your new keystores. + In this example, the keystore and truststore are using different files. Your configuration might use the same file for both the keystore and the @@ -587,7 +584,7 @@ keytool -delete -noprompt -alias -keystore config/elastic-stack-ca.p12 [%collapsible%open] .Command parameters ==== - `-alias`:: Name of the old CA certificate that you want to remove from your + `-alias`:: Name of the keystore alias for the old CA certificate that you want to remove from your truststore. ==== @@ -781,4 +778,4 @@ security certificate for the HTTP layer. elasticsearch.ssl.certificateAuthorities: KBN_PATH_CONF/elasticsearch-ca.pem ---- -. Restart {kib}. \ No newline at end of file +. Restart {kib}. From e7d031f4e6a04130326d49d0b3e601449478fa58 Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Mon, 12 Jul 2021 17:07:55 -0400 Subject: [PATCH 19/24] Update instructions to use a single keystore, plus other review changes --- .../update-tls-certificates.asciidoc | 317 +++++++----------- 1 file changed, 127 insertions(+), 190 deletions(-) diff --git a/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc b/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc index 7c10bed163223..6b39544ea1245 100644 --- a/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc +++ b/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc @@ -1,13 +1,14 @@ [[update-node-certs]] == Updating node security certificates -You need to update your TLS certificates if your current node certificates might -expire soon, you're adding new nodes to your secured cluster, or a security -breach has broken the trust of your certificate chain. In these instances where -<>, you can sign new -certificates using the original Certificate Authority (CA) that you used to sign your existing certificates. - -If you have to trust a new CA from your organization, or you need to generate a new CA yourself, you need to use this new CA to sign the new node certificates and instruct your nodes to trust the new CA. -<> for each +You might need to update your TLS certificates if your current node +certificates expire soon, you're adding new nodes to your secured cluster, or +a security breach has broken the trust of your certificate chain. + +In instances where you have access to the original Certificate Authority (CA) key and certificate that you used to sign your existing node certificates (and where your CA has not been compromised), you can +<>. + +If you have to trust a new CA from your organization, or you need to generate a new CA yourself, you need to use this new CA to sign the new node certificates and instruct your nodes to trust the new CA. In this case, you'll +<> for each node that is signed by the new CA certificate and instruct your nodes to trust this certificate chain. @@ -15,13 +16,12 @@ Depending on which certificates are expiring, you might need to update the certificates for the transport layer, the HTTP layer, or both. Regardless of the scenario, {es} monitors the SSL resources for updates -on a five-second interval by default. You can just copy the new +by default, on a five-second interval. You can just copy the new certificate and key files (or keystore) into the {es} configuration directory and your nodes will detect the changes and reload the keys and certificates. Because {es} doesn't reload the `elasticsearch.yml` configuration, -you must use *the same file names* so that {es} refreshes the -certificates and keys. +you must use *the same file names* if you want to take advantage of automatic certificate and key reloading. If you need to update the `elasticsearch.yml` configuration or change passwords for keys or keystores that are stored in the @@ -60,8 +60,8 @@ certificate. If you have access to the CA used to sign your existing certificates, you only need to replace the certificates and keys for each node in your cluster. If you -replace your existing certificates and keys on each node use the same filenames, -{es} reloads the files starts using the new certificates and keys. +replace your existing certificates and keys on each node and use the same +filenames, {es} reloads the files starts using the new certificates and keys. You don't have to restart each node, but doing so forces new TLS connections and is <> when updating certificates. Therefore, the following steps include a node restart after updating each @@ -87,11 +87,6 @@ TIP: If your CA has changed, complete the steps in The following examples use PKCS#12 files, but the same steps apply to JKS keystores. -Rather than run the `elasticsearch-certutil` tool once for each node, create an -`instances.yml` file that contains information about each of your nodes. You can -then use the `elasticsearch-certutil` tool to generate certificates for all of -your nodes with a single command. - . Open the `ES_PATH_CONF/elasticsearch.yml` file and check the names of the keystores that are currently in use. You'll use the same names for your new certificate. @@ -108,69 +103,26 @@ xpack.security.transport.ssl.truststore.path: config/elastic-stack-ca.p12 xpack.security.transport.ssl.truststore.type: PKCS12 ---- -. On any node in your cluster, create an `instances.yml` file that contains -information about each of your nodes. Include all IP addresses and DNS names -that you use to identify each node. -+ -[source,yaml] ----- -instances: - - name: "node1" - ip: - - "192.168.1.101" - dns: - - "node1" - - "node1.mydomain.com" - - name: "node2" - ip: - - "192.168.1.102" - dns: - - "node2" - - "node2.mydomain.com" - - name: "node3" - ip: - - "192.168.1.103" - dns: - - "node3" - - "node3.mydomain.com" - - name: "node4" - ip: - - "192.168.1.104" - dns: - - "node4" - - "node4.mydomain.com" ----- - -. Using your existing CA, generate a keystore for each of your nodes. You must +. Using your existing CA, generate a keystore for your nodes. You must use the CA that was used to sign the certificate currently in use. + [source,shell] ---- -./bin/elasticsearch-certutil cert --in instances.yml --ca elastic-stack-ca.p12 +./bin/elasticsearch-certutil cert --ca elastic-stack-ca.p12 ---- + [%collapsible%open] .Command parameters ==== - `-in`:: Specifies the name of the input YAML file (`instances.yml`) - containing information about each of your nodes. - `--ca `:: Name of the CA keystore used to sign your certificates. + If you used the `elasticsearch-certutil` tool to generate your existing CA, + the keystore name defaults to `elastic-stack-ca.p12`. ==== a. Enter a name for the output file or accept the default of - `certificate-bundle.zip`. - - b. When prompted, enter a password for each node certificate. It's good - practice to use a different password for each node certificate and store the - files in a secure location. - - c. Decompress the `certificate-bundle.zip` file. The output contains a - directory for each of your nodes with a `.p12` file. + `elastic-certificates.p12`. - d. Rename the `.p12` file to match the existing file name - specified by the `xpack.security.transport.ssl.keystore.path` variable in - the `elasticsearch.yml` file on each node. + b. When prompted, enter a password for the node keystore. . If you entered a password when creating the node keystore that is different from the current keystore password, run the following command to store the @@ -183,16 +135,16 @@ password in the {es} keystore: ---- -- -. [[start-rolling-restart,step 5]]On the current node in your cluster where you're updating the keystore, +. [[start-rolling-restart,step 4]]On the current node in your cluster where you're updating the keystore, start a <>. + Stop at the step indicating *Perform any needed changes*, and then proceed to the next step in this procedure. -. [[replace-keystores]]Replace your existing keystore with the new keystore, ensuring that the -file names match. For example, `node1.p12`. +. [[replace-keystores]]Replace your existing keystore with the new keystore, +ensuring that the file names match. For example, `elastic-certificates.p12`. + -If your +IMPORTANT: If your <>, then save the keystore with a new filename so that {es} doesn't attempt to reload the file before you update the password. @@ -203,20 +155,23 @@ For example: + [source,yaml] ---- -xpack.security.transport.ssl.keystore.path: config/node1.p12 +xpack.security.transport.ssl.keystore.path: config/elastic-certificates.p12 xpack.security.transport.ssl.keystore.type: PKCS12 xpack.security.transport.ssl.truststore.path: config/elastic-stack-ca.p12 xpack.security.transport.ssl.truststore.type: PKCS12 ---- -. Start the node where you updated the keystore, and then complete the remaining -steps for a <>. +. Start the node where you updated the keystore. -. [[verify-keystore,step 9]](Optional) Use the <> to verify that -{es} loaded the new keystore. +. [[verify-keystore,step 8]](Optional) Use the +<> to verify that {es} loaded the new +keystore. -. One node at a time, complete <> through -<> until you've updated all keystores in your cluster. +. If you're only updating certificates for the transport layer (and not the HTTP layer), then complete <> through <> one node at a time until you've updated all keystores in your cluster. You can then +complete the remaining steps for a <>. ++ +Otherwise, do not complete a rolling restart and proceed to the steps for +generating a new certificate for the HTTP layer. [discrete] [[transport-layer-sameca-whatsnext]] @@ -233,9 +188,7 @@ this certificate when they connect to {es}. NOTE: If your organization has its own CA, you'll need to <>. CSRs contain -information that your CA uses to generate and sign a certificate -instead of using self-signed certificates that the `elasticsearch-certutil` tool -generates. +information that your CA uses to generate and sign a certificate. . On any node in your cluster where {es} is installed, run the {es} HTTP certificate tool. @@ -267,9 +220,9 @@ explaining how to use these files. Each certificate will have its own private key, and will be issued for a specific hostname or IP address. - g. When prompted, enter the name of the first node in your cluster. Use the - same node name as the value for the `node.name` parameter in the - `elasticsearch.yml` file. + g. When prompted, enter the name of the first node in your cluster. It's + helpful to use the same node name as the value for the `node.name` + parameter in the `elasticsearch.yml` file. h. Enter all hostnames used to connect to your first node. These hostnames will be added as DNS names in the Subject Alternative Name (SAN) field in your certificate. @@ -284,7 +237,7 @@ List every hostname and variant used to connect to your cluster over HTTPS. your private key when prompted. . Unzip the generated `elasticsearch-ssl-http.zip` file. This compressed file - contains one directory for both {es} and {kib}. Within the `/elasticsearch` + contains two directories; one each for {es} and {kib}. Within the `/elasticsearch` directory is a directory for each node that you specified with it's own `http.p12` file. For example: + @@ -315,7 +268,7 @@ List every hostname and variant used to connect to your cluster over HTTPS. -- . If necessary, rename the `http.p12` file to match the name of your existing -certificate for HTTP client communications. +certificate for HTTP client communications. For example, `node1-http.p12`. . [[start-rolling-restart-http,step 5]]On the current node in your cluster where you're updating the keystore, start a <>. @@ -326,7 +279,7 @@ the next step in this procedure. . Replace your existing keystore with the new keystore, ensuring that the file names match. For example, `node1-http.p12`. + -If your +IMPORTANT: If your <>, then save the keystore with a new filename so that {es} doesn't attempt to reload the file before you update the password. @@ -368,8 +321,8 @@ If you have to trust a new CA from your organization, or you need to generate a [[node-certs-different-transport]] ==== Generate a new certificate for the transport layer Create a new CA certificate and add it to your existing CA truststore. After -{es} reloads the file, you can remove the old CA certificate from your -truststore. +you finish updating your certificates for all nodes, you can remove the old CA +certificate from your truststore (but not before!). NOTE: The following examples use PKCS#12 files, but the same steps apply to JKS keystores. @@ -393,12 +346,6 @@ xpack.security.transport.ssl.truststore.type: PKCS12 . On *any* node in your cluster, generate a new CA certificate. You only need to complete this step one time. + -NOTE: If your organization has its own CA, you'll need to -<>. CSRs contain -information that your CA uses to generate and sign a security certificate -instead of using self-signed certificates that the `elasticsearch-certutil` tool -generates. -+ [source,shell] ---- ./bin/elasticsearch-certutil ca --pem @@ -446,75 +393,40 @@ keytool -importcert -trustcacerts -noprompt -keystore elastic-stack-ca.p12 \ `-file`:: Name of the new CA certificate to import. ==== -. Check that the new CA certificate was added to your truststore. The output -should contain both the existing CA certificate and your new certificate. Each -CA certificate is identified by the `friendlyName` attribute in the output. -+ -When prompted, enter the password for the CA truststore. +. [[check-ca-truststore]] Check that the new CA certificate was added to your +truststore. + [source,shell] ---- keytool -keystore config/elastic-stack-ca.p12 -list ---- +When prompted, enter the password for the CA truststore. ++ +The output should contain both the existing CA certificate and your new +certificate. If you previously used the `elasticsearch-certutil` tool to +generate your keystore, the alias of the old CA defaults to `ca` and the type of +entry is `PrivateKeyEntry`. [discrete] [[node-certs-different-nodes]] ==== Generate a new certificate for each node in your cluster Now that your CA truststore is updated, use your new CA certificate to sign -a certificate for each node in your cluster. Rather than run the -`elasticsearch-certutil` tool once for each node, create an `instances.yml` file -that contains information about each of your nodes. You can then use the -`elasticsearch-certutil` tool to generate certificates for all of your nodes -with a single command. +a certificate for your nodes. -. On any node in your cluster, create an `instances.yml` file that contains -information about each of your nodes. Include all IP addresses and DNS names -that you use to identify each node. -+ -[source,yaml] ----- -instances: - - name: "node1" - ip: - - "192.168.1.101" - dns: - - "node1" - - "node1.mydomain.com" - - name: "node2" - ip: - - "192.168.1.102" - dns: - - "node2" - - "node2.mydomain.com" - - name: "node3" - ip: - - "192.168.1.103" - dns: - - "node3" - - "node3.mydomain.com" - - name: "node4" - ip: - - "192.168.1.104" - dns: - - "node4" - - "node4.mydomain.com" ----- - -. Using the new CA certificate and key, create a new certificate for each node -in your cluster. Include the `instances.yml` file that you created previously. +NOTE: If your organization has its own CA, you'll need to +<>. CSRs contain +information that your CA uses to generate and sign a security certificate. + +. Using the new CA certificate and key, create a new certificate for your nodes. + [source,shell] ---- -./bin/elasticsearch-certutil cert --in instances.yml --ca-cert ca/ca.crt \ ---ca-key ca/ca.key +./bin/elasticsearch-certutil cert --ca-cert ca/ca.crt --ca-key ca/ca.key ---- + [%collapsible%open] .Command parameters ==== - `-in`:: Specifies the name of the input YAML file (`instances.yml`) - containing information about each of your nodes. - `--ca-cert`:: Specifies the path to your new CA certificate (`ca.crt`) in PEM format. You must also specify the `--ca-key` parameter. @@ -523,20 +435,11 @@ in your cluster. Include the `instances.yml` file that you created previously. ==== a. Enter a name for the output file or accept the default of - `certificate-bundle.zip`. + `elastic-certificates.p12`. - b. When prompted, enter a password for each node certificate. It's good - practice to use a different password for each node certificate and store the - files in a secure location. + b. When prompted, enter a password for your node certificate. - c. Decompress the `certificate-bundle.zip` file. The output contains a - directory for each of your nodes with a `.p12` file. - - d. Rename the `.p12` file to match the existing file name - specified by the `xpack.security.transport.ssl.keystore.path` variable in - the `elasticsearch.yml` file on each node. - -. [[start-rolling-restart-newca,step 3]]On the current node in your cluster where +. [[start-rolling-restart-newca,step 2]]On the current node in your cluster where you're updating the keystore, start a <>. + @@ -544,9 +447,9 @@ Stop at the step indicating *Perform any needed changes*, and then proceed to the next step in this procedure. . Replace your existing keystore with the new keystore, ensuring that the -file names match. For example, `.p12`. +file names match. For example, `elastic-certificates.p12`. + -If your +IMPORTANT: If your <>, then save the keystore with a new filename so that {es} doesn't attempt to reload the file before you update the password. @@ -557,27 +460,36 @@ For example: + [source,yaml] ---- -xpack.security.transport.ssl.keystore.path: config/.p12 +xpack.security.transport.ssl.keystore.path: config/elastic-certificates.p12 xpack.security.transport.ssl.keystore.type: PKCS12 xpack.security.transport.ssl.truststore.path: config/elastic-stack-ca.p12 xpack.security.transport.ssl.truststore.type: PKCS12 ---- -. Start the node where you updated the keystore, and then complete the remaining -steps for a <>. +. Start the node where you updated the keystore. -. [[verify-keystore-newca,step 7]](Optional) Use the <> to verify that -{es} loaded the new keystore. +. [[verify-keystore-newca,step 6]](Optional) Use the <> to verify that {es} loaded the new keystore. -. One node at a time, complete <> through -<> until you've updated all keystores in your cluster. +. If you're only updating certificates for the transport layer (and not the HTTP +layer), then complete <> through +<> one node at a time until you've updated all keystores +in your cluster. You can then complete the remaining steps for a +<>. ++ +Otherwise, do not complete a rolling restart and proceed to the steps for +generating a new certificate for the HTTP layer. -. (Optional) After rotating keystores on each node in your cluster, remove the -old CA certificate from your truststore. +. (Optional) After rotating keystores on each node in your cluster, +<> and then remove +the old CA certificate. ++ +If you previously used the `elasticsearch-certutil` tool to generate your +keystore, the alias of the old CA defaults to `ca` and the type of entry is +`PrivateKeyEntry`. + [source,shell] ---- -keytool -delete -noprompt -alias -keystore config/elastic-stack-ca.p12 \ +keytool -delete -noprompt -alias ca -keystore config/elastic-stack-ca.p12 \ -storepass ---- + @@ -608,6 +520,48 @@ information that your CA uses to generate and sign a security certificate instead of using self-signed certificates that the `elasticsearch-certutil` tool generates. +Before generating new certificates for the HTTP layer, you need to go to all the clients that connect to {es} (such as {kib}, {beats}, {ls}, and any language +clients) and configure them to also trust the new CA (`ca.crt`) that you +generated. + +. For *every* client that connects to {es}, import the new `ca.crt` certificate +into your existing CA truststore for the HTTP layer. This step ensures that your +cluster trusts the new CA certificate. This example uses the Java `keytool` +utility to import the certificate into the `http.p12` CA truststore. ++ +[source,shell] +---- +keytool -importcert -trustcacerts -noprompt -keystore http.p12 \ +-storepass -alias new-ca -file ca.crt +---- ++ +[%collapsible%open] +.Command parameters +==== + `-keystore`:: Name of the HTTP truststore that you are importing the new CA + certificate into. + + `-storepass`:: Password for the CA truststore. + + `-alias`:: Name that you want to assign to the new CA certificate entry in + the keystore. + + `-file`:: Name of the new CA certificate to import. +==== + +. Check that the new CA certificate was added to your truststore. ++ +[source,shell] +---- +keytool -keystore config/http.p12 -list +---- +When prompted, enter the password for the CA truststore. ++ +The output should contain both the existing CA certificate and your new +certificate. If you previously used the `elasticsearch-certutil` tool to +generate your keystore, the alias of the old CA defaults to `http` and the type +of entry is `PrivateKeyEntry`. + . On any node in your cluster where {es} is installed, run the {es} HTTP certificate tool. + @@ -687,10 +641,9 @@ List every hostname and variant used to connect to your cluster over HTTPS. -- . If necessary, rename each `http.p12` file to match the name of your existing -certificate for HTTP client communications. This keystore contains both a -certificate and key. +certificate for HTTP client communications. For example, `node1-http.p12`. -. [[start-rolling-restart-http-newca,step 5]]On the current node in your cluster where you're updating the keystore, +. [[start-rolling-restart-http-newca,step 7]]On the current node in your cluster where you're updating the keystore, start a <>. + Stop at the step indicating *Perform any needed changes*, and then proceed to @@ -699,7 +652,7 @@ the next step in this procedure. . Replace your existing keystore with the new keystore, ensuring that the file names match. For example, `node1-http.p12`. + -If your +IMPORTANT: If your <>, then save the keystore with a new filename so that {es} doesn't attempt to reload the file before you update the password. @@ -725,28 +678,12 @@ to the secure settings in {es}. . Start the node where you updated the keystore, and then complete the remaining steps for a <>. -. [[verify-keystore-http-newca,step 10]](Optional) Use the <> to verify that +. [[verify-keystore-http-newca,step 12]](Optional) Use the <> to verify that {es} loaded the new keystore. . One node at a time, complete <> through <> until you've updated all keystores in your cluster. -. (Optional) After rotating keystores on each node in your cluster, remove the -old CA certificate from your truststore. -+ -[source,shell] ----- -keytool -delete -noprompt -alias -keystore config/http.p12 \ --storepass ----- -+ -[%collapsible%open] -.Command parameters -==== - `-alias`:: Name of the old CA certificate that you want to remove from your - truststore. -==== - [discrete] [[http-kibana-newca-whatsnext]] ==== What's next? From fefc0bed8d36ccfa4493df2458f215d089f4f912 Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Fri, 16 Jul 2021 16:17:43 -0400 Subject: [PATCH 20/24] Incorporating another round of review comments --- .../update-tls-certificates.asciidoc | 86 ++++++++----------- 1 file changed, 36 insertions(+), 50 deletions(-) diff --git a/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc b/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc index 6b39544ea1245..8c00e24e52a44 100644 --- a/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc +++ b/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc @@ -4,13 +4,14 @@ You might need to update your TLS certificates if your current node certificates expire soon, you're adding new nodes to your secured cluster, or a security breach has broken the trust of your certificate chain. -In instances where you have access to the original Certificate Authority (CA) key and certificate that you used to sign your existing node certificates (and where your CA has not been compromised), you can +In instances where you have access to the original Certificate Authority (CA) key and certificate that you used to sign your existing node certificates (and where you can still trust your CA), you can <>. -If you have to trust a new CA from your organization, or you need to generate a new CA yourself, you need to use this new CA to sign the new node certificates and instruct your nodes to trust the new CA. In this case, you'll -<> for each -node that is signed by the new CA certificate and instruct your nodes to trust -this certificate chain. +If you have to trust a new CA from your organization, or you need to generate +a new CA yourself, you need to use this new CA to sign the new node +certificates and instruct your nodes to trust the new CA. In this case, you'll +<> and +instruct your nodes to trust this certificate chain. Depending on which certificates are expiring, you might need to update the certificates for the transport layer, the HTTP layer, or both. @@ -95,12 +96,20 @@ In this example, the keystore and truststore are pointing to different files. Your configuration might use the same file that contains the certificate and CA. In this case, include the path to that file for both the keystore and truststore. + +[NOTE] +==== +These instructions assume that the provided certificate is signed by a trusted +CA and the verification mode is set to `certificate`. This setting ensures that +nodes to not attempt to perform hostname verification. +==== ++ [source,yaml] ---- xpack.security.transport.ssl.keystore.path: config/elastic-certificates.p12 xpack.security.transport.ssl.keystore.type: PKCS12 xpack.security.transport.ssl.truststore.path: config/elastic-stack-ca.p12 xpack.security.transport.ssl.truststore.type: PKCS12 +xpack.security.transport.ssl.verification_mode: certificate ---- . Using your existing CA, generate a keystore for your nodes. You must @@ -170,7 +179,7 @@ keystore. . If you're only updating certificates for the transport layer (and not the HTTP layer), then complete <> through <> one node at a time until you've updated all keystores in your cluster. You can then complete the remaining steps for a <>. + -Otherwise, do not complete a rolling restart and proceed to the steps for +Otherwise, do not complete a rolling restart. Instead, proceed to the steps for generating a new certificate for the HTTP layer. [discrete] @@ -320,8 +329,8 @@ If you have to trust a new CA from your organization, or you need to generate a [[node-certs-different-transport]] ==== Generate a new certificate for the transport layer -Create a new CA certificate and add it to your existing CA truststore. After -you finish updating your certificates for all nodes, you can remove the old CA +Create a new CA certificate, or get the CA certificate of your organization, +and add it to your existing CA truststore. After you finish updating your certificates for all nodes, you can remove the old CA certificate from your truststore (but not before!). NOTE: The following examples use PKCS#12 files, but the same steps apply to JKS @@ -333,7 +342,14 @@ for your new keystores. + In this example, the keystore and truststore are using different files. Your configuration might use the same file for both the keystore and the -truststore. Elastic recommends using separate files. +truststore. ++ +[NOTE] +==== +These instructions assume that the provided certificate is signed by a trusted +CA and the verification mode is set to `certificate`. This setting ensures that +nodes to not attempt to perform hostname verification. +==== + [source,yaml] ---- @@ -341,6 +357,7 @@ xpack.security.transport.ssl.keystore.path: config/elastic-certificates.p12 xpack.security.transport.ssl.keystore.type: PKCS12 xpack.security.transport.ssl.truststore.path: config/elastic-stack-ca.p12 xpack.security.transport.ssl.truststore.type: PKCS12 +xpack.security.transport.ssl.verification_mode: certificate ---- . On *any* node in your cluster, generate a new CA certificate. You only need @@ -476,7 +493,7 @@ layer), then complete <> through in your cluster. You can then complete the remaining steps for a <>. + -Otherwise, do not complete a rolling restart and proceed to the steps for +Otherwise, do not complete a rolling restart. Instead, proceed to the steps for generating a new certificate for the HTTP layer. . (Optional) After rotating keystores on each node in your cluster, @@ -520,47 +537,16 @@ information that your CA uses to generate and sign a security certificate instead of using self-signed certificates that the `elasticsearch-certutil` tool generates. -Before generating new certificates for the HTTP layer, you need to go to all the clients that connect to {es} (such as {kib}, {beats}, {ls}, and any language -clients) and configure them to also trust the new CA (`ca.crt`) that you -generated. - -. For *every* client that connects to {es}, import the new `ca.crt` certificate -into your existing CA truststore for the HTTP layer. This step ensures that your -cluster trusts the new CA certificate. This example uses the Java `keytool` -utility to import the certificate into the `http.p12` CA truststore. -+ -[source,shell] ----- -keytool -importcert -trustcacerts -noprompt -keystore http.p12 \ --storepass -alias new-ca -file ca.crt ----- -+ -[%collapsible%open] -.Command parameters -==== - `-keystore`:: Name of the HTTP truststore that you are importing the new CA - certificate into. - - `-storepass`:: Password for the CA truststore. - - `-alias`:: Name that you want to assign to the new CA certificate entry in - the keystore. - - `-file`:: Name of the new CA certificate to import. -==== +.Update clients to trust the new CA +**** +After generating (but before using) new certificates for the HTTP layer, you +need to go to all the clients that connect to {es} (such as {kib}, {beats}, +{ls}, and any language clients) and configure them to also trust the new CA +(`ca.crt`) that you generated. -. Check that the new CA certificate was added to your truststore. -+ -[source,shell] ----- -keytool -keystore config/http.p12 -list ----- -When prompted, enter the password for the CA truststore. -+ -The output should contain both the existing CA certificate and your new -certificate. If you previously used the `elasticsearch-certutil` tool to -generate your keystore, the alias of the old CA defaults to `http` and the type -of entry is `PrivateKeyEntry`. +This process is different for each client, so refer to your client's +documentation for trusting certificates. +**** . On any node in your cluster where {es} is installed, run the {es} HTTP certificate tool. From 688fba3350dcfdc8ed8c4352b2165bca669f1fd1 Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Tue, 27 Jul 2021 12:34:05 -0400 Subject: [PATCH 21/24] Minor updates from reviewer feedback --- .../update-tls-certificates.asciidoc | 65 ++++++++++++++----- 1 file changed, 47 insertions(+), 18 deletions(-) diff --git a/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc b/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc index 8c00e24e52a44..44ae3de5952df 100644 --- a/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc +++ b/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc @@ -2,7 +2,9 @@ == Updating node security certificates You might need to update your TLS certificates if your current node certificates expire soon, you're adding new nodes to your secured cluster, or -a security breach has broken the trust of your certificate chain. +a security breach has broken the trust of your certificate chain. Use the +<> API to check when your certificates are +expiring. In instances where you have access to the original Certificate Authority (CA) key and certificate that you used to sign your existing node certificates (and where you can still trust your CA), you can <>. @@ -88,9 +90,9 @@ TIP: If your CA has changed, complete the steps in The following examples use PKCS#12 files, but the same steps apply to JKS keystores. -. Open the `ES_PATH_CONF/elasticsearch.yml` file and check the names of the -keystores that are currently in use. You'll use the same names for your new -certificate. +. Open the `ES_PATH_CONF/elasticsearch.yml` file and check the names and +locations of the keystores that are currently in use. You'll use the same names +for your new certificate. + In this example, the keystore and truststore are pointing to different files. Your configuration might use the same file that contains the certificate and CA. @@ -247,7 +249,7 @@ List every hostname and variant used to connect to your cluster over HTTPS. . Unzip the generated `elasticsearch-ssl-http.zip` file. This compressed file contains two directories; one each for {es} and {kib}. Within the `/elasticsearch` - directory is a directory for each node that you specified with it's own + directory is a directory for each node that you specified with its own `http.p12` file. For example: + -- @@ -311,8 +313,17 @@ to the secure settings in {es}. ./bin/elasticsearch-keystore add xpack.security.http.ssl.keystore.secure_password ---- -. Start the node where you updated the keystore, and then complete the remaining -steps for a <>. +. Start the node where you updated the keystore. ++ +-- +Submit a `_cat/nodes` request to confirm that the node joined the cluster: + +[source,console] +---- +GET _cat/nodes +---- + +-- . [[verify-keystore-http,step 10]](Optional) Use the <> to verify that {es} loaded the new keystore. @@ -320,6 +331,9 @@ steps for a <>. . One node at a time, complete <> through <> until you've updated all keystores in your cluster. +. Complete the remaining steps for a <>, +beginning with the step to *Reenable shard allocation*. + [[update-node-certs-different]] === Update security certificates with a different CA ++++ @@ -336,8 +350,8 @@ certificate from your truststore (but not before!). NOTE: The following examples use PKCS#12 files, but the same steps apply to JKS keystores. -. Open the `ES_PATH_CONF/elasticsearch.yml` file and check the names of the -keystores that are currently in use. You'll use the same names +. Open the `ES_PATH_CONF/elasticsearch.yml` file and check the names and +locations of the keystores that are currently in use. You'll use the same names for your new keystores. + In this example, the keystore and truststore are using different files. @@ -361,7 +375,8 @@ xpack.security.transport.ssl.verification_mode: certificate ---- . On *any* node in your cluster, generate a new CA certificate. You only need -to complete this step one time. +to complete this step one time. If you're using the CA certificate of your +organization, then skip this step. + [source,shell] ---- @@ -496,7 +511,7 @@ in your cluster. You can then complete the remaining steps for a Otherwise, do not complete a rolling restart. Instead, proceed to the steps for generating a new certificate for the HTTP layer. -. (Optional) After rotating keystores on each node in your cluster, +. (Optional) After replacing keystores on each node in your cluster, <> and then remove the old CA certificate. + @@ -540,12 +555,14 @@ generates. .Update clients to trust the new CA **** After generating (but before using) new certificates for the HTTP layer, you -need to go to all the clients that connect to {es} (such as {kib}, {beats}, -{ls}, and any language clients) and configure them to also trust the new CA -(`ca.crt`) that you generated. +need to go to all the clients that connect to {es} (such as {beats}, {ls}, and +any language clients) and configure them to also trust the new CA (`ca.crt`) +that you generated. This process is different for each client, so refer to your client's -documentation for trusting certificates. +documentation for trusting certificates. You'll +<> +after generating the necessary certificates in this procedure. **** . On any node in your cluster where {es} is installed, run the {es} HTTP @@ -597,7 +614,7 @@ List every hostname and variant used to connect to your cluster over HTTPS. . Unzip the generated `elasticsearch-ssl-http.zip` file. This compressed file contains one directory for both {es} and {kib}. Within the `/elasticsearch` - directory is a directory for each node that you specified with it's own + directory is a directory for each node that you specified with its own `http.p12` file. For example: + -- @@ -661,8 +678,17 @@ to the secure settings in {es}. ./bin/elasticsearch-keystore add xpack.security.http.ssl.keystore.secure_password ---- -. Start the node where you updated the keystore, and then complete the remaining -steps for a <>. +. Start the node where you updated the keystore. ++ +-- +Submit a `_cat/nodes` request to confirm that the node joined the cluster: + +[source,console] +---- +GET _cat/nodes +---- + +-- . [[verify-keystore-http-newca,step 12]](Optional) Use the <> to verify that {es} loaded the new keystore. @@ -670,6 +696,9 @@ steps for a <>. . One node at a time, complete <> through <> until you've updated all keystores in your cluster. +. Complete the remaining steps for a <>, +beginning with the step to *Reenable shard allocation*. + [discrete] [[http-kibana-newca-whatsnext]] ==== What's next? From 474eeab0e9e92bb431088900f2e57e40e7ff801a Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Tue, 27 Jul 2021 14:42:15 -0400 Subject: [PATCH 22/24] Clarifying examples and fixing numbering --- .../update-tls-certificates.asciidoc | 47 ++++++++++++++++--- 1 file changed, 41 insertions(+), 6 deletions(-) diff --git a/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc b/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc index 44ae3de5952df..3a8d3ad538a20 100644 --- a/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc +++ b/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc @@ -177,6 +177,15 @@ xpack.security.transport.ssl.truststore.type: PKCS12 . [[verify-keystore,step 8]](Optional) Use the <> to verify that {es} loaded the new keystore. ++ +-- + +[source, console] +---- +GET /_ssl/certificates +---- + +-- . If you're only updating certificates for the transport layer (and not the HTTP layer), then complete <> through <> one node at a time until you've updated all keystores in your cluster. You can then complete the remaining steps for a <>. @@ -316,7 +325,7 @@ to the secure settings in {es}. . Start the node where you updated the keystore. + -- -Submit a `_cat/nodes` request to confirm that the node joined the cluster: +Use the <> to confirm that the node joined the cluster: [source,console] ---- @@ -325,8 +334,16 @@ GET _cat/nodes -- -. [[verify-keystore-http,step 10]](Optional) Use the <> to verify that -{es} loaded the new keystore. +. [[verify-keystore-http,step 10]](Optional) Use the <> to verify that {es} loaded the new keystore. ++ +-- + +[source, console] +---- +GET /_ssl/certificates +---- + +-- . One node at a time, complete <> through <> until you've updated all keystores in your cluster. @@ -501,6 +518,15 @@ xpack.security.transport.ssl.truststore.type: PKCS12 . Start the node where you updated the keystore. . [[verify-keystore-newca,step 6]](Optional) Use the <> to verify that {es} loaded the new keystore. ++ +-- + +[source, console] +---- +GET /_ssl/certificates +---- + +-- . If you're only updating certificates for the transport layer (and not the HTTP layer), then complete <> through @@ -646,7 +672,7 @@ List every hostname and variant used to connect to your cluster over HTTPS. . If necessary, rename each `http.p12` file to match the name of your existing certificate for HTTP client communications. For example, `node1-http.p12`. -. [[start-rolling-restart-http-newca,step 7]]On the current node in your cluster where you're updating the keystore, +. [[start-rolling-restart-http-newca,step 5]]On the current node in your cluster where you're updating the keystore, start a <>. + Stop at the step indicating *Perform any needed changes*, and then proceed to @@ -681,7 +707,7 @@ to the secure settings in {es}. . Start the node where you updated the keystore. + -- -Submit a `_cat/nodes` request to confirm that the node joined the cluster: +Use the <> to confirm that the node joined the cluster: [source,console] ---- @@ -690,8 +716,17 @@ GET _cat/nodes -- -. [[verify-keystore-http-newca,step 12]](Optional) Use the <> to verify that +. [[verify-keystore-http-newca,step 10]](Optional) Use the <> to verify that {es} loaded the new keystore. ++ +-- + +[source, console] +---- +GET /_ssl/certificates +---- + +-- . One node at a time, complete <> through <> until you've updated all keystores in your cluster. From 34bf6defa14b8cd55d8808b89e01f78a447f1046 Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Wed, 28 Jul 2021 10:08:29 -0400 Subject: [PATCH 23/24] Skip tests that are creating unnecessary noise --- .../securing-communications/update-tls-certificates.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc b/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc index 3a8d3ad538a20..f6e88f4ff22f6 100644 --- a/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc +++ b/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc @@ -184,7 +184,7 @@ keystore. ---- GET /_ssl/certificates ---- - +// TEST[skip:creates a lot of noise] -- . If you're only updating certificates for the transport layer (and not the HTTP layer), then complete <> through <> one node at a time until you've updated all keystores in your cluster. You can then @@ -725,7 +725,7 @@ GET _cat/nodes ---- GET /_ssl/certificates ---- - +// TEST[skip:creates a lot of noise] -- . One node at a time, complete <> through From aa0b16a7ee09814f2e3afea31ca4063b7a26864c Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Wed, 28 Jul 2021 12:33:47 -0400 Subject: [PATCH 24/24] Quieting other tests --- .../securing-communications/update-tls-certificates.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc b/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc index f6e88f4ff22f6..b5f63b092ee25 100644 --- a/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc +++ b/x-pack/docs/en/security/securing-communications/update-tls-certificates.asciidoc @@ -342,7 +342,7 @@ GET _cat/nodes ---- GET /_ssl/certificates ---- - +// TEST[skip:creates a lot of noise] -- . One node at a time, complete <> through @@ -525,7 +525,7 @@ xpack.security.transport.ssl.truststore.type: PKCS12 ---- GET /_ssl/certificates ---- - +// TEST[skip:creates a lot of noise] -- . If you're only updating certificates for the transport layer (and not the HTTP