From 2bb27683500a155b097b672a9b0dd24375c15d67 Mon Sep 17 00:00:00 2001 From: Elliot Barlas Date: Tue, 11 Aug 2026 23:22:54 -0700 Subject: [PATCH 1/5] Document transport TLS certificate expiry behavior Manual transport TLS setup recommends using the same PKCS#12 file for both keystore and truststore without explaining that expired peer certificates may still be accepted. This gap confused users and was raised in elastic/security#1966. Clarify that elastic-certificates.p12 acts as a cluster- membership key and note the expiry implications when the same file is used for keystore and truststore. Add a brief auto- configuration note in security-files.md covering transport.p12, enrollment tokens, and a cross-link to the manual setup guide. --- .../deploy/self-managed/_snippets/security-files.md | 6 ++++-- deploy-manage/security/set-up-basic-security.md | 8 ++++++-- 2 files changed, 10 insertions(+), 4 deletions(-) diff --git a/deploy-manage/deploy/self-managed/_snippets/security-files.md b/deploy-manage/deploy/self-managed/_snippets/security-files.md index b38a487f45..c832ac134b 100644 --- a/deploy-manage/deploy/self-managed/_snippets/security-files.md +++ b/deploy-manage/deploy/self-managed/_snippets/security-files.md @@ -7,7 +7,7 @@ When you install {{es}}, the following certificates and keys are generated in th : Keystore that contains the key and certificate for the HTTP layer for this node. `transport.p12` -: Keystore that contains the key and certificate for the transport layer for all the nodes in your cluster. +: Keystore that contains the transport certificate, private key, and cluster CA for this node. `http.p12` and `transport.p12` are password-protected PKCS#12 keystores. {{es}} stores the passwords for these keystores as [secure settings](/deploy-manage/security/secure-settings.md). To retrieve the passwords so that you can inspect or change the keystore contents, use the [`bin/elasticsearch-keystore`](elasticsearch://reference/elasticsearch/command-line-tools/elasticsearch-keystore.md) tool. @@ -21,4 +21,6 @@ Use the following command to retrieve the password for `transport.p12`: ```sh bin/elasticsearch-keystore show xpack.security.transport.ssl.keystore.secure_password -``` \ No newline at end of file +``` + +Security auto-configuration sets `certs/transport.p12` as both the transport keystore and truststore on each node. Auto-generated transport certificates have a long validity period and are unlikely to expire under normal operation. To add nodes, use an [enrollment token](/deploy-manage/maintenance/add-and-remove-elasticsearch-nodes.md#_enroll_nodes_in_an_existing_cluster_5) rather than copying `transport.p12` between nodes. For manual transport TLS setup and certificate expiry behavior when the same PKCS#12 file is shared across all nodes, refer to [Set up transport TLS](/deploy-manage/security/set-up-basic-security.md). \ No newline at end of file diff --git a/deploy-manage/security/set-up-basic-security.md b/deploy-manage/security/set-up-basic-security.md index 8ee7470042..01c55ae775 100644 --- a/deploy-manage/security/set-up-basic-security.md +++ b/deploy-manage/security/set-up-basic-security.md @@ -89,7 +89,7 @@ Now that you’ve obtained your certificates, you’ll update your cluster to us These steps assume that you [generated a CA and certificates](#generate-certificates) using `elasticsearch-certutil`. The `xpack.security.transport.ssl` settings that you need to set differ if you're using a certificate generated with an external CA. Refer to [Transport TLS/SSL settings](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#transport-tls-ssl-settings) for a full list of available settings. ::::{note} -{{es}} monitors all files such as certificates, keys, keystores, or truststores that are configured as values of TLS-related node settings. If you update any of these files, such as when your hostnames change or your certificates are due to expire, {{es}} reloads them. The files are polled for changes at a frequency determined by the global {{es}} `resource.reload.interval.high` setting, which defaults to 5 seconds. +{{es}} monitors all files such as certificates, keys, keystores, or truststores that are configured as values of TLS-related node settings. If you update any of these files, such as when your hostnames change or your certificates are due to expire, {{es}} reloads them. The files are polled for changes at a frequency determined by the global {{es}} `resource.reload.interval.high` setting, which defaults to 5 seconds. Reloading an expired certificate does not cause {{es}} to reject peer connections when the same file is used for both keystore and truststore. :::: @@ -113,7 +113,7 @@ Complete the following steps **for each node in your cluster**. To join the same 3. Add the following settings to enable internode communication and provide access to the node’s certificate. - Because you are using the same `elastic-certificates.p12` file on every node in your cluster, set the verification mode to `certificate`: + Use the same `elastic-certificates.p12` file on every node in your cluster. This file acts as a cluster-membership key: any node with a copy of the file can join the cluster and will trust other nodes using the same file. Because every node presents the same certificate, set the verification mode to `certificate`: ```yaml xpack.security.transport.ssl.enabled: true @@ -123,6 +123,10 @@ Complete the following steps **for each node in your cluster**. To join the same xpack.security.transport.ssl.truststore.path: elastic-certificates.p12 ``` + ::::{note} + When the same PKCS#12 file is configured as both the keystore and truststore, peer node certificates in that file are trusted directly. In this configuration, {{es}} does not reject connections from nodes presenting an expired certificate from the same file, even when `verification_mode` is set to `certificate`. Internode communication remains encrypted, and the cluster can continue to operate normally, including restarts and adding new nodes that use the same file. Plan certificate rotation for security hygiene, and refer to [Update security certificates with the same CA](./same-ca.md) when replacing transport certificates. + :::: + 1. If you want to use hostname verification, set the verification mode to `full`. You should generate a different certificate for each host that matches the DNS or IP address. See the `xpack.security.transport.ssl.verification_mode` parameter in [TLS settings](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#transport-tls-ssl-settings). 3. If you entered a password when creating the node certificate, run the following commands to store the password in the {{es}} keystore: From ff75afa425c94b69afd30053fd9c6e9d9461650b Mon Sep 17 00:00:00 2001 From: Elliot Barlas Date: Wed, 12 Aug 2026 21:42:11 -0700 Subject: [PATCH 2/5] Revert transport.p12 to reduce change scope --- deploy-manage/deploy/self-managed/_snippets/security-files.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/deploy-manage/deploy/self-managed/_snippets/security-files.md b/deploy-manage/deploy/self-managed/_snippets/security-files.md index c832ac134b..56b32d7b8e 100644 --- a/deploy-manage/deploy/self-managed/_snippets/security-files.md +++ b/deploy-manage/deploy/self-managed/_snippets/security-files.md @@ -7,7 +7,7 @@ When you install {{es}}, the following certificates and keys are generated in th : Keystore that contains the key and certificate for the HTTP layer for this node. `transport.p12` -: Keystore that contains the transport certificate, private key, and cluster CA for this node. +: Keystore that contains the key and certificate for the transport layer for all the nodes in your cluster. `http.p12` and `transport.p12` are password-protected PKCS#12 keystores. {{es}} stores the passwords for these keystores as [secure settings](/deploy-manage/security/secure-settings.md). To retrieve the passwords so that you can inspect or change the keystore contents, use the [`bin/elasticsearch-keystore`](elasticsearch://reference/elasticsearch/command-line-tools/elasticsearch-keystore.md) tool. From 7f25469be96cbe322efd04ab1d6a10c3cc329953 Mon Sep 17 00:00:00 2001 From: Elliot Barlas Date: Wed, 12 Aug 2026 21:43:56 -0700 Subject: [PATCH 3/5] Remove sentence in certificate expiry note --- deploy-manage/security/set-up-basic-security.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/deploy-manage/security/set-up-basic-security.md b/deploy-manage/security/set-up-basic-security.md index 01c55ae775..f46069f36b 100644 --- a/deploy-manage/security/set-up-basic-security.md +++ b/deploy-manage/security/set-up-basic-security.md @@ -124,7 +124,7 @@ Complete the following steps **for each node in your cluster**. To join the same ``` ::::{note} - When the same PKCS#12 file is configured as both the keystore and truststore, peer node certificates in that file are trusted directly. In this configuration, {{es}} does not reject connections from nodes presenting an expired certificate from the same file, even when `verification_mode` is set to `certificate`. Internode communication remains encrypted, and the cluster can continue to operate normally, including restarts and adding new nodes that use the same file. Plan certificate rotation for security hygiene, and refer to [Update security certificates with the same CA](./same-ca.md) when replacing transport certificates. + When the same PKCS#12 file is configured as both the keystore and truststore, peer node certificates in that file are trusted directly. In this configuration, {{es}} does not reject connections from nodes presenting an expired certificate from the same file, even when `verification_mode` is set to `certificate`. Internode communication remains encrypted, and the cluster can continue to operate normally, including restarts and adding new nodes that use the same file. :::: 1. If you want to use hostname verification, set the verification mode to `full`. You should generate a different certificate for each host that matches the DNS or IP address. See the `xpack.security.transport.ssl.verification_mode` parameter in [TLS settings](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#transport-tls-ssl-settings). From 9bea469a24abe552feb0b52df9b34ee282f059d6 Mon Sep 17 00:00:00 2001 From: Elliot Barlas Date: Wed, 12 Aug 2026 22:24:07 -0700 Subject: [PATCH 4/5] Remove another sentence --- deploy-manage/security/set-up-basic-security.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/deploy-manage/security/set-up-basic-security.md b/deploy-manage/security/set-up-basic-security.md index f46069f36b..ae7139073f 100644 --- a/deploy-manage/security/set-up-basic-security.md +++ b/deploy-manage/security/set-up-basic-security.md @@ -89,7 +89,7 @@ Now that you’ve obtained your certificates, you’ll update your cluster to us These steps assume that you [generated a CA and certificates](#generate-certificates) using `elasticsearch-certutil`. The `xpack.security.transport.ssl` settings that you need to set differ if you're using a certificate generated with an external CA. Refer to [Transport TLS/SSL settings](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#transport-tls-ssl-settings) for a full list of available settings. ::::{note} -{{es}} monitors all files such as certificates, keys, keystores, or truststores that are configured as values of TLS-related node settings. If you update any of these files, such as when your hostnames change or your certificates are due to expire, {{es}} reloads them. The files are polled for changes at a frequency determined by the global {{es}} `resource.reload.interval.high` setting, which defaults to 5 seconds. Reloading an expired certificate does not cause {{es}} to reject peer connections when the same file is used for both keystore and truststore. +{{es}} monitors all files such as certificates, keys, keystores, or truststores that are configured as values of TLS-related node settings. If you update any of these files, such as when your hostnames change or your certificates are due to expire, {{es}} reloads them. The files are polled for changes at a frequency determined by the global {{es}} `resource.reload.interval.high` setting, which defaults to 5 seconds. :::: From 8ac384c0f61a129286c939455b48084eb8a58f3e Mon Sep 17 00:00:00 2001 From: Elliot Barlas Date: Thu, 13 Aug 2026 10:35:38 -0700 Subject: [PATCH 5/5] Improve the description --- deploy-manage/security/set-up-basic-security.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/deploy-manage/security/set-up-basic-security.md b/deploy-manage/security/set-up-basic-security.md index ae7139073f..75eaab79eb 100644 --- a/deploy-manage/security/set-up-basic-security.md +++ b/deploy-manage/security/set-up-basic-security.md @@ -124,7 +124,7 @@ Complete the following steps **for each node in your cluster**. To join the same ``` ::::{note} - When the same PKCS#12 file is configured as both the keystore and truststore, peer node certificates in that file are trusted directly. In this configuration, {{es}} does not reject connections from nodes presenting an expired certificate from the same file, even when `verification_mode` is set to `certificate`. Internode communication remains encrypted, and the cluster can continue to operate normally, including restarts and adding new nodes that use the same file. + When the same file is configured as both the keystore and truststore, or when only `keystore.path` is set and {{es}} uses that file as the truststore, peer node certificates in the file are trusted directly. The same behavior applies if a peer's leaf certificate is listed in `xpack.security.transport.ssl.certificate_authorities`. In these configurations, {{es}} does not reject connections from nodes presenting an expired certificate that is directly trusted, regardless of the `verification_mode` setting. Internode communication remains encrypted, and the cluster can continue to operate normally, including restarts and adding new nodes that use the same certificate material. :::: 1. If you want to use hostname verification, set the verification mode to `full`. You should generate a different certificate for each host that matches the DNS or IP address. See the `xpack.security.transport.ssl.verification_mode` parameter in [TLS settings](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#transport-tls-ssl-settings).