From 7ac57ec7365e5a3359cd918b655d2b6d4b1ddfd0 Mon Sep 17 00:00:00 2001 From: David Turner Date: Thu, 6 Nov 2025 14:10:03 +0000 Subject: [PATCH 01/13] Add note about transport mTLS Until recently, public CAs would issue certificates with an Extended Key Usage set that includes the `clientAuth` value, allowing these certificates to be used for mTLS. Nonetheless it is a mistake to use such certificates for mTLS. To prevent users from continuing to make this mistake, all certificates issued by public CAs will soon omit the `clientAuth` usage value. Elasticsearch will by default use mTLS for inter-node connections, and we've recently encountered some users who have been obtaining their transport certificates from such public CAs and mistakenly using them for mTLS. This commit adds some documentation clarifying the security model and giving clearer recommendations in this area. --- .../configuration-reference/security-settings.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/reference/elasticsearch/configuration-reference/security-settings.md b/docs/reference/elasticsearch/configuration-reference/security-settings.md index cb1a4e65f0436..5fe3b66e39e6d 100644 --- a/docs/reference/elasticsearch/configuration-reference/security-settings.md +++ b/docs/reference/elasticsearch/configuration-reference/security-settings.md @@ -1927,7 +1927,17 @@ You can configure the following TLS/SSL settings. `xpack.security.transport.ssl.client_authentication` -: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Controls the server’s behavior in regard to requesting a certificate from client connections. Valid values are `required`, `optional`, and `none`. `required` forces a client to present a certificate, while `optional` requests a client certificate but the client is not required to present one. Defaults to `required`. +: ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Controls the node's behavior in regard to requesting a certificate when accepting an inbound transport connections from another {{es}} node. Valid values are `required`, `optional`, and `none`. The default is `required` which means that the connecting node must present a valid client certificate during the connection process. May also be set to `optional` which means that a client certificate is requested but the connecting node may choose not to present one, or `none` which means that no client certificate is even requested during the connection process. + + ::::{note} + By default {{es}} uses mutual TLS (mTLS) to ensure the security of node-to-node transport connections within a cluster. Mutual TLS means that both nodes in a connection must present a valid certificate to the other node when establishing the connection. {{es}} checks that each of these certificates is issued by a certificate authority that the other node trusts for this purpose. The set of certificate authorities trusted for transport connections are defined with settings in the `xpack.security.transport.ssl.*` namespace such as `xpack.security.transport.ssl.certificate_authorities` and `xpack.security.transport.ssl.truststore.path`. + + To realize the full benefits of the mTLS security model, obtain your transport certificates from a certificate authority that only issues certificates to {{es}} nodes which are permitted to connect to your cluster. Do not use a public certificate authority, nor an organization-wide private certificate authority, because such certificate authorities issue certificates to entities other than the {{es}} nodes which are permitted to connect to your cluster. Public certificate authorities generally issue certificates which cannot be used as a client certificate in mTLS anyway. The recommended best practice is to use a different private certificate authority for each {{es}} cluster. + + The security requirements for transport certificates (as defined by the `xpack.security.transport.ssl.*` settings) are significantly different from the security requirements for HTTP certificates (as defined by the `xpack.security.http.ssl.*` settings). HTTP connections do not generally use mTLS since HTTP has its own authentication mechanisms, so HTTP certificates do not usually need to permit client authentication. It often makes sense to obtain the nodes' HTTP certificates from a public certificate authority, or from an organization-wide private certificate authority. + + If your environment has some other way to prevent unauthorized node-to-node connections, you may prefer not to use mTLS for transport connections. In this case, turn mTLS off in this context by setting `xpack.security.transport.ssl.client_authentication: none`. With this configuration {{es}} can still use (non-mutual) TLS to ensure the confidentiality and integrity of node-to-node traffic. If you are using non-mutual TLS for transport connections then you may use certificates issued by a public certificate authority, or an organization-wide private certificate authority, for your transport certificates. + :::: `xpack.security.transport.ssl.verification_mode` : ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Defines how to verify the certificates presented by another party in the TLS connection: From 3f0237581523634a0883e8f820b4ed945038173f Mon Sep 17 00:00:00 2001 From: David Turner Date: Thu, 6 Nov 2025 14:44:54 +0000 Subject: [PATCH 02/13] Move wall of text to section top --- .../security-settings.md | 20 +++++++++---------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/docs/reference/elasticsearch/configuration-reference/security-settings.md b/docs/reference/elasticsearch/configuration-reference/security-settings.md index 5fe3b66e39e6d..8f7e19bb14486 100644 --- a/docs/reference/elasticsearch/configuration-reference/security-settings.md +++ b/docs/reference/elasticsearch/configuration-reference/security-settings.md @@ -1911,7 +1911,15 @@ PKCS#12 files are configured in the same way as Java keystore files: ## Transport TLS/SSL settings [transport-tls-ssl-settings] -You can configure the following TLS/SSL settings. +The settings in this section relate to node-to-node transport connections. + +By default {{es}} uses mutual TLS (mTLS) to ensure the security of node-to-node transport connections within a cluster. Mutual TLS means that both nodes in a connection must present a valid certificate to the other node when establishing the connection. {{es}} checks that each of these certificates is issued by a certificate authority that the other node trusts for this purpose. The set of certificate authorities trusted for transport connections are defined with settings in the `xpack.security.transport.ssl.*` namespace such as `xpack.security.transport.ssl.certificate_authorities` and `xpack.security.transport.ssl.truststore.path`. + +To realize the full benefits of the mTLS security model, obtain your transport certificates from a certificate authority that only issues certificates to {{es}} nodes which are permitted to connect to your cluster. Do not use a public certificate authority, nor an organization-wide private certificate authority, because such certificate authorities issue certificates to entities other than the {{es}} nodes which are permitted to connect to your cluster. Public certificate authorities generally issue certificates which cannot be used as a client certificate in mTLS anyway. The recommended best practice is to use a different private certificate authority for each {{es}} cluster. + +The security requirements for transport certificates (as defined by the `xpack.security.transport.ssl.*` settings) are significantly different from the security requirements for HTTP certificates (as defined by the `xpack.security.http.ssl.*` settings). HTTP connections do not generally use mTLS since HTTP has its own authentication mechanisms, so HTTP certificates do not usually need to permit client authentication. It often makes sense to obtain the nodes' HTTP certificates from a public certificate authority, or from an organization-wide private certificate authority. + +If your environment has some other way to prevent unauthorized node-to-node connections, you may prefer not to use mTLS for transport connections. In this case, turn mTLS off in this context by setting `xpack.security.transport.ssl.client_authentication: none`. You may still use (non-mutual) TLS to ensure the confidentiality and integrity of node-to-node traffic by setting `xpack.security.transport.ssl.enabled: true`. If you are using non-mutual TLS for transport connections then you may use certificates issued by a public certificate authority, or an organization-wide private certificate authority, for your transport certificates. `xpack.security.transport.ssl.enabled` : ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Used to enable or disable TLS/SSL on the transport networking layer, which nodes use to communicate with each other. The default is `false`. @@ -1929,16 +1937,6 @@ You can configure the following TLS/SSL settings. `xpack.security.transport.ssl.client_authentication` : ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Controls the node's behavior in regard to requesting a certificate when accepting an inbound transport connections from another {{es}} node. Valid values are `required`, `optional`, and `none`. The default is `required` which means that the connecting node must present a valid client certificate during the connection process. May also be set to `optional` which means that a client certificate is requested but the connecting node may choose not to present one, or `none` which means that no client certificate is even requested during the connection process. - ::::{note} - By default {{es}} uses mutual TLS (mTLS) to ensure the security of node-to-node transport connections within a cluster. Mutual TLS means that both nodes in a connection must present a valid certificate to the other node when establishing the connection. {{es}} checks that each of these certificates is issued by a certificate authority that the other node trusts for this purpose. The set of certificate authorities trusted for transport connections are defined with settings in the `xpack.security.transport.ssl.*` namespace such as `xpack.security.transport.ssl.certificate_authorities` and `xpack.security.transport.ssl.truststore.path`. - - To realize the full benefits of the mTLS security model, obtain your transport certificates from a certificate authority that only issues certificates to {{es}} nodes which are permitted to connect to your cluster. Do not use a public certificate authority, nor an organization-wide private certificate authority, because such certificate authorities issue certificates to entities other than the {{es}} nodes which are permitted to connect to your cluster. Public certificate authorities generally issue certificates which cannot be used as a client certificate in mTLS anyway. The recommended best practice is to use a different private certificate authority for each {{es}} cluster. - - The security requirements for transport certificates (as defined by the `xpack.security.transport.ssl.*` settings) are significantly different from the security requirements for HTTP certificates (as defined by the `xpack.security.http.ssl.*` settings). HTTP connections do not generally use mTLS since HTTP has its own authentication mechanisms, so HTTP certificates do not usually need to permit client authentication. It often makes sense to obtain the nodes' HTTP certificates from a public certificate authority, or from an organization-wide private certificate authority. - - If your environment has some other way to prevent unauthorized node-to-node connections, you may prefer not to use mTLS for transport connections. In this case, turn mTLS off in this context by setting `xpack.security.transport.ssl.client_authentication: none`. With this configuration {{es}} can still use (non-mutual) TLS to ensure the confidentiality and integrity of node-to-node traffic. If you are using non-mutual TLS for transport connections then you may use certificates issued by a public certificate authority, or an organization-wide private certificate authority, for your transport certificates. - :::: - `xpack.security.transport.ssl.verification_mode` : ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Defines how to verify the certificates presented by another party in the TLS connection: From e79dbc6123b12cf20dc334fb76618958ea400566 Mon Sep 17 00:00:00 2001 From: David Turner Date: Thu, 6 Nov 2025 14:54:48 +0000 Subject: [PATCH 03/13] Wordsmithery --- .../configuration-reference/security-settings.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/reference/elasticsearch/configuration-reference/security-settings.md b/docs/reference/elasticsearch/configuration-reference/security-settings.md index 8f7e19bb14486..b0372bf538f81 100644 --- a/docs/reference/elasticsearch/configuration-reference/security-settings.md +++ b/docs/reference/elasticsearch/configuration-reference/security-settings.md @@ -1913,11 +1913,11 @@ PKCS#12 files are configured in the same way as Java keystore files: The settings in this section relate to node-to-node transport connections. -By default {{es}} uses mutual TLS (mTLS) to ensure the security of node-to-node transport connections within a cluster. Mutual TLS means that both nodes in a connection must present a valid certificate to the other node when establishing the connection. {{es}} checks that each of these certificates is issued by a certificate authority that the other node trusts for this purpose. The set of certificate authorities trusted for transport connections are defined with settings in the `xpack.security.transport.ssl.*` namespace such as `xpack.security.transport.ssl.certificate_authorities` and `xpack.security.transport.ssl.truststore.path`. +By default {{es}} uses mutual TLS (mTLS) to ensure the security of node-to-node transport connections within a cluster. Mutual TLS means that both nodes in a connection must present a valid certificate to the other node when establishing the connection. Each {{es}} node checks that the certificate presented by the other node is issued by a certificate authority that it trusts for this purpose. The set of certificate authorities that a node trusts to issue certificates for transport connections is defined with settings in the `xpack.security.transport.ssl.*` namespace such as `xpack.security.transport.ssl.certificate_authorities` and `xpack.security.transport.ssl.truststore.path`. Certificates used for mTLS must either have no Extended Key Usage extension, or must have an Extended Key Usage extension that includes the `clientAuth` and `serverAuth` values. -To realize the full benefits of the mTLS security model, obtain your transport certificates from a certificate authority that only issues certificates to {{es}} nodes which are permitted to connect to your cluster. Do not use a public certificate authority, nor an organization-wide private certificate authority, because such certificate authorities issue certificates to entities other than the {{es}} nodes which are permitted to connect to your cluster. Public certificate authorities generally issue certificates which cannot be used as a client certificate in mTLS anyway. The recommended best practice is to use a different private certificate authority for each {{es}} cluster. +To realize the full benefits of the mTLS security model, obtain your transport certificates from a certificate authority that only issues certificates to {{es}} nodes which are permitted to connect to your cluster. Do not use a public certificate authority, nor an organization-wide private certificate authority, because such certificate authorities issue certificates to entities other than the {{es}} nodes which are permitted to connect to your cluster. Public certificate authorities generally do not issue certificates with an Extended Key Usage extension that omits the `clientAuth` value and therefore cannot be used for mTLS anyway. The recommended best practice is to use a different private certificate authority for each {{es}} cluster. -The security requirements for transport certificates (as defined by the `xpack.security.transport.ssl.*` settings) are significantly different from the security requirements for HTTP certificates (as defined by the `xpack.security.http.ssl.*` settings). HTTP connections do not generally use mTLS since HTTP has its own authentication mechanisms, so HTTP certificates do not usually need to permit client authentication. It often makes sense to obtain the nodes' HTTP certificates from a public certificate authority, or from an organization-wide private certificate authority. +The security requirements for transport certificates (as defined by the `xpack.security.transport.ssl.*` settings) are significantly different from the security requirements for HTTP certificates (as defined by the `xpack.security.http.ssl.*` settings). HTTP connections do not generally use mTLS since HTTP has its own authentication mechanisms, so HTTP certificates do not usually need to include the `clientAuth` value in their Extended Key Usage extension. It often makes sense to obtain the nodes' HTTP certificates from a public certificate authority, or from an organization-wide private certificate authority. If your environment has some other way to prevent unauthorized node-to-node connections, you may prefer not to use mTLS for transport connections. In this case, turn mTLS off in this context by setting `xpack.security.transport.ssl.client_authentication: none`. You may still use (non-mutual) TLS to ensure the confidentiality and integrity of node-to-node traffic by setting `xpack.security.transport.ssl.enabled: true`. If you are using non-mutual TLS for transport connections then you may use certificates issued by a public certificate authority, or an organization-wide private certificate authority, for your transport certificates. From dd98a0618085055a6a6253b79ac19512cb882f8d Mon Sep 17 00:00:00 2001 From: David Turner Date: Thu, 6 Nov 2025 14:58:51 +0000 Subject: [PATCH 04/13] tweak --- .../elasticsearch/configuration-reference/security-settings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/elasticsearch/configuration-reference/security-settings.md b/docs/reference/elasticsearch/configuration-reference/security-settings.md index b0372bf538f81..eafb01b8747e6 100644 --- a/docs/reference/elasticsearch/configuration-reference/security-settings.md +++ b/docs/reference/elasticsearch/configuration-reference/security-settings.md @@ -1913,7 +1913,7 @@ PKCS#12 files are configured in the same way as Java keystore files: The settings in this section relate to node-to-node transport connections. -By default {{es}} uses mutual TLS (mTLS) to ensure the security of node-to-node transport connections within a cluster. Mutual TLS means that both nodes in a connection must present a valid certificate to the other node when establishing the connection. Each {{es}} node checks that the certificate presented by the other node is issued by a certificate authority that it trusts for this purpose. The set of certificate authorities that a node trusts to issue certificates for transport connections is defined with settings in the `xpack.security.transport.ssl.*` namespace such as `xpack.security.transport.ssl.certificate_authorities` and `xpack.security.transport.ssl.truststore.path`. Certificates used for mTLS must either have no Extended Key Usage extension, or must have an Extended Key Usage extension that includes the `clientAuth` and `serverAuth` values. +By default {{es}} uses mutual TLS (mTLS) to ensure the security of node-to-node transport connections within a cluster. Mutual TLS means that both nodes in a connection must present a valid certificate to the other node when establishing the connection. Each {{es}} node checks that the certificate presented by the other node is issued by a certificate authority that it trusts for this purpose. The set of certificate authorities that a node trusts to issue certificates for transport connections is defined with settings in the `xpack.security.transport.ssl.*` namespace such as `xpack.security.transport.ssl.certificate_authorities` and `xpack.security.transport.ssl.truststore.path`. Certificates used for mTLS either must have no Extended Key Usage extension, or must have an Extended Key Usage extension that includes the `clientAuth` and `serverAuth` values. To realize the full benefits of the mTLS security model, obtain your transport certificates from a certificate authority that only issues certificates to {{es}} nodes which are permitted to connect to your cluster. Do not use a public certificate authority, nor an organization-wide private certificate authority, because such certificate authorities issue certificates to entities other than the {{es}} nodes which are permitted to connect to your cluster. Public certificate authorities generally do not issue certificates with an Extended Key Usage extension that omits the `clientAuth` value and therefore cannot be used for mTLS anyway. The recommended best practice is to use a different private certificate authority for each {{es}} cluster. From b99da6d8c435cf5f8294a797757aef559c820fa0 Mon Sep 17 00:00:00 2001 From: David Turner Date: Thu, 6 Nov 2025 20:21:38 +0000 Subject: [PATCH 05/13] Fix incorrect negation --- .../elasticsearch/configuration-reference/security-settings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/elasticsearch/configuration-reference/security-settings.md b/docs/reference/elasticsearch/configuration-reference/security-settings.md index eafb01b8747e6..4bf3b8f573593 100644 --- a/docs/reference/elasticsearch/configuration-reference/security-settings.md +++ b/docs/reference/elasticsearch/configuration-reference/security-settings.md @@ -1915,7 +1915,7 @@ The settings in this section relate to node-to-node transport connections. By default {{es}} uses mutual TLS (mTLS) to ensure the security of node-to-node transport connections within a cluster. Mutual TLS means that both nodes in a connection must present a valid certificate to the other node when establishing the connection. Each {{es}} node checks that the certificate presented by the other node is issued by a certificate authority that it trusts for this purpose. The set of certificate authorities that a node trusts to issue certificates for transport connections is defined with settings in the `xpack.security.transport.ssl.*` namespace such as `xpack.security.transport.ssl.certificate_authorities` and `xpack.security.transport.ssl.truststore.path`. Certificates used for mTLS either must have no Extended Key Usage extension, or must have an Extended Key Usage extension that includes the `clientAuth` and `serverAuth` values. -To realize the full benefits of the mTLS security model, obtain your transport certificates from a certificate authority that only issues certificates to {{es}} nodes which are permitted to connect to your cluster. Do not use a public certificate authority, nor an organization-wide private certificate authority, because such certificate authorities issue certificates to entities other than the {{es}} nodes which are permitted to connect to your cluster. Public certificate authorities generally do not issue certificates with an Extended Key Usage extension that omits the `clientAuth` value and therefore cannot be used for mTLS anyway. The recommended best practice is to use a different private certificate authority for each {{es}} cluster. +To realize the full benefits of the mTLS security model, obtain your transport certificates from a certificate authority that only issues certificates to {{es}} nodes which are permitted to connect to your cluster. Do not use a public certificate authority, nor an organization-wide private certificate authority, because such certificate authorities issue certificates to entities other than the {{es}} nodes which are permitted to connect to your cluster. Public certificate authorities generally issue certificates with an Extended Key Usage extension that omits the `clientAuth` value and therefore cannot be used for mTLS anyway. The recommended best practice is to use a different private certificate authority for each {{es}} cluster. The security requirements for transport certificates (as defined by the `xpack.security.transport.ssl.*` settings) are significantly different from the security requirements for HTTP certificates (as defined by the `xpack.security.http.ssl.*` settings). HTTP connections do not generally use mTLS since HTTP has its own authentication mechanisms, so HTTP certificates do not usually need to include the `clientAuth` value in their Extended Key Usage extension. It often makes sense to obtain the nodes' HTTP certificates from a public certificate authority, or from an organization-wide private certificate authority. From b3a443609b18e31abbf669cadaec1ed870ac6242 Mon Sep 17 00:00:00 2001 From: David Turner Date: Fri, 7 Nov 2025 09:36:43 +0000 Subject: [PATCH 06/13] Add some callouts --- .../configuration-reference/security-settings.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/reference/elasticsearch/configuration-reference/security-settings.md b/docs/reference/elasticsearch/configuration-reference/security-settings.md index 4bf3b8f573593..d2a38b8e9430a 100644 --- a/docs/reference/elasticsearch/configuration-reference/security-settings.md +++ b/docs/reference/elasticsearch/configuration-reference/security-settings.md @@ -1913,14 +1913,26 @@ PKCS#12 files are configured in the same way as Java keystore files: The settings in this section relate to node-to-node transport connections. +::::{important} +Transport connections between {{es}} nodes are security-critical and you must protect them carefully. A malicious actor who can observe or interfere with the raw traffic on a node-to-node transport connection will be able to read or modify the data in your cluster. A malicious actor who can establish a transport connection with a node in your cluster may be able to invoke certain system-internal APIs, some of which may allow them to read or modify the data in your cluster. +:::: + By default {{es}} uses mutual TLS (mTLS) to ensure the security of node-to-node transport connections within a cluster. Mutual TLS means that both nodes in a connection must present a valid certificate to the other node when establishing the connection. Each {{es}} node checks that the certificate presented by the other node is issued by a certificate authority that it trusts for this purpose. The set of certificate authorities that a node trusts to issue certificates for transport connections is defined with settings in the `xpack.security.transport.ssl.*` namespace such as `xpack.security.transport.ssl.certificate_authorities` and `xpack.security.transport.ssl.truststore.path`. Certificates used for mTLS either must have no Extended Key Usage extension, or must have an Extended Key Usage extension that includes the `clientAuth` and `serverAuth` values. To realize the full benefits of the mTLS security model, obtain your transport certificates from a certificate authority that only issues certificates to {{es}} nodes which are permitted to connect to your cluster. Do not use a public certificate authority, nor an organization-wide private certificate authority, because such certificate authorities issue certificates to entities other than the {{es}} nodes which are permitted to connect to your cluster. Public certificate authorities generally issue certificates with an Extended Key Usage extension that omits the `clientAuth` value and therefore cannot be used for mTLS anyway. The recommended best practice is to use a different private certificate authority for each {{es}} cluster. +::::{warning} +Anyone who can obtain a certificate from a certificate authority that your {{es}} cluster trusts for mTLS on transport connections will be able to use this certificate to establish a transport connection with a node in your cluster. A malicious actor with such a certificate may be able to use such a transport connection to invoke certain system-internal APIs, some of which may allow them to read or modify the data in your cluster. +:::: + The security requirements for transport certificates (as defined by the `xpack.security.transport.ssl.*` settings) are significantly different from the security requirements for HTTP certificates (as defined by the `xpack.security.http.ssl.*` settings). HTTP connections do not generally use mTLS since HTTP has its own authentication mechanisms, so HTTP certificates do not usually need to include the `clientAuth` value in their Extended Key Usage extension. It often makes sense to obtain the nodes' HTTP certificates from a public certificate authority, or from an organization-wide private certificate authority. If your environment has some other way to prevent unauthorized node-to-node connections, you may prefer not to use mTLS for transport connections. In this case, turn mTLS off in this context by setting `xpack.security.transport.ssl.client_authentication: none`. You may still use (non-mutual) TLS to ensure the confidentiality and integrity of node-to-node traffic by setting `xpack.security.transport.ssl.enabled: true`. If you are using non-mutual TLS for transport connections then you may use certificates issued by a public certificate authority, or an organization-wide private certificate authority, for your transport certificates. +::::{warning} +If you turn off mTLS by setting `xpack.security.transport.ssl.client_authentication: none` then anyone with network access to a node in your {{es}} cluster will be able to establish a transport connection with that node. A malicious actor with this access may be able to use such a transport connection to invoke certain system-internal APIs, some of which may allow them to read or modify the data in your cluster. Use mTLS to protect your node-to-node transport connections unless you are absolutely certain that unauthorized network access to these nodes cannot occur. +:::: + `xpack.security.transport.ssl.enabled` : ([Static](docs-content://deploy-manage/stack-settings.md#static-cluster-setting)) Used to enable or disable TLS/SSL on the transport networking layer, which nodes use to communicate with each other. The default is `false`. From 3f97d897dc787630252c2f188129ed983f949291 Mon Sep 17 00:00:00 2001 From: David Turner Date: Fri, 7 Nov 2025 09:41:13 +0000 Subject: [PATCH 07/13] More security words --- .../elasticsearch/configuration-reference/security-settings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/elasticsearch/configuration-reference/security-settings.md b/docs/reference/elasticsearch/configuration-reference/security-settings.md index d2a38b8e9430a..fbd12f7594041 100644 --- a/docs/reference/elasticsearch/configuration-reference/security-settings.md +++ b/docs/reference/elasticsearch/configuration-reference/security-settings.md @@ -1917,7 +1917,7 @@ The settings in this section relate to node-to-node transport connections. Transport connections between {{es}} nodes are security-critical and you must protect them carefully. A malicious actor who can observe or interfere with the raw traffic on a node-to-node transport connection will be able to read or modify the data in your cluster. A malicious actor who can establish a transport connection with a node in your cluster may be able to invoke certain system-internal APIs, some of which may allow them to read or modify the data in your cluster. :::: -By default {{es}} uses mutual TLS (mTLS) to ensure the security of node-to-node transport connections within a cluster. Mutual TLS means that both nodes in a connection must present a valid certificate to the other node when establishing the connection. Each {{es}} node checks that the certificate presented by the other node is issued by a certificate authority that it trusts for this purpose. The set of certificate authorities that a node trusts to issue certificates for transport connections is defined with settings in the `xpack.security.transport.ssl.*` namespace such as `xpack.security.transport.ssl.certificate_authorities` and `xpack.security.transport.ssl.truststore.path`. Certificates used for mTLS either must have no Extended Key Usage extension, or must have an Extended Key Usage extension that includes the `clientAuth` and `serverAuth` values. +By default {{es}} uses mutual TLS (mTLS) to ensure the security of node-to-node transport connections within a cluster. Mutual TLS means that data is encrypted in transit, ensuring confidentiality and integrity, and also that both nodes in a connection must present a valid certificate to the other node when establishing the connection. Each {{es}} node checks that the certificate presented by the other node is issued by a certificate authority that it trusts for this purpose, ensuring that the nodes are authorized to establish this connection. The set of certificate authorities that a node trusts to issue certificates for transport connections is defined with settings in the `xpack.security.transport.ssl.*` namespace such as `xpack.security.transport.ssl.certificate_authorities` and `xpack.security.transport.ssl.truststore.path`. Certificates used for mTLS either must have no Extended Key Usage extension, or must have an Extended Key Usage extension that includes the `clientAuth` and `serverAuth` values. To realize the full benefits of the mTLS security model, obtain your transport certificates from a certificate authority that only issues certificates to {{es}} nodes which are permitted to connect to your cluster. Do not use a public certificate authority, nor an organization-wide private certificate authority, because such certificate authorities issue certificates to entities other than the {{es}} nodes which are permitted to connect to your cluster. Public certificate authorities generally issue certificates with an Extended Key Usage extension that omits the `clientAuth` value and therefore cannot be used for mTLS anyway. The recommended best practice is to use a different private certificate authority for each {{es}} cluster. From 6b917ac1bd584fbd4a75d92ac9ad7caf19cb9bf1 Mon Sep 17 00:00:00 2001 From: David Turner Date: Fri, 7 Nov 2025 09:52:54 +0000 Subject: [PATCH 08/13] Optional is also bad --- .../elasticsearch/configuration-reference/security-settings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/elasticsearch/configuration-reference/security-settings.md b/docs/reference/elasticsearch/configuration-reference/security-settings.md index fbd12f7594041..b035271305e13 100644 --- a/docs/reference/elasticsearch/configuration-reference/security-settings.md +++ b/docs/reference/elasticsearch/configuration-reference/security-settings.md @@ -1930,7 +1930,7 @@ The security requirements for transport certificates (as defined by the `xpack.s If your environment has some other way to prevent unauthorized node-to-node connections, you may prefer not to use mTLS for transport connections. In this case, turn mTLS off in this context by setting `xpack.security.transport.ssl.client_authentication: none`. You may still use (non-mutual) TLS to ensure the confidentiality and integrity of node-to-node traffic by setting `xpack.security.transport.ssl.enabled: true`. If you are using non-mutual TLS for transport connections then you may use certificates issued by a public certificate authority, or an organization-wide private certificate authority, for your transport certificates. ::::{warning} -If you turn off mTLS by setting `xpack.security.transport.ssl.client_authentication: none` then anyone with network access to a node in your {{es}} cluster will be able to establish a transport connection with that node. A malicious actor with this access may be able to use such a transport connection to invoke certain system-internal APIs, some of which may allow them to read or modify the data in your cluster. Use mTLS to protect your node-to-node transport connections unless you are absolutely certain that unauthorized network access to these nodes cannot occur. +If you turn off mTLS by setting `xpack.security.transport.ssl.client_authentication` to `optional` or `none` then anyone with network access to a node in your {{es}} cluster will be able to establish a transport connection with that node. A malicious actor with this access may be able to use such a transport connection to invoke certain system-internal APIs, some of which may allow them to read or modify the data in your cluster. Use mTLS to protect your node-to-node transport connections unless you are absolutely certain that unauthorized network access to these nodes cannot occur. :::: `xpack.security.transport.ssl.enabled` From c1eb51490280cf02e777464737f8ce7dcabae088 Mon Sep 17 00:00:00 2001 From: David Turner Date: Fri, 7 Nov 2025 10:24:00 +0000 Subject: [PATCH 09/13] Iter --- .../elasticsearch/configuration-reference/security-settings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/elasticsearch/configuration-reference/security-settings.md b/docs/reference/elasticsearch/configuration-reference/security-settings.md index b035271305e13..ad8f028b3ea8a 100644 --- a/docs/reference/elasticsearch/configuration-reference/security-settings.md +++ b/docs/reference/elasticsearch/configuration-reference/security-settings.md @@ -1917,7 +1917,7 @@ The settings in this section relate to node-to-node transport connections. Transport connections between {{es}} nodes are security-critical and you must protect them carefully. A malicious actor who can observe or interfere with the raw traffic on a node-to-node transport connection will be able to read or modify the data in your cluster. A malicious actor who can establish a transport connection with a node in your cluster may be able to invoke certain system-internal APIs, some of which may allow them to read or modify the data in your cluster. :::: -By default {{es}} uses mutual TLS (mTLS) to ensure the security of node-to-node transport connections within a cluster. Mutual TLS means that data is encrypted in transit, ensuring confidentiality and integrity, and also that both nodes in a connection must present a valid certificate to the other node when establishing the connection. Each {{es}} node checks that the certificate presented by the other node is issued by a certificate authority that it trusts for this purpose, ensuring that the nodes are authorized to establish this connection. The set of certificate authorities that a node trusts to issue certificates for transport connections is defined with settings in the `xpack.security.transport.ssl.*` namespace such as `xpack.security.transport.ssl.certificate_authorities` and `xpack.security.transport.ssl.truststore.path`. Certificates used for mTLS either must have no Extended Key Usage extension, or must have an Extended Key Usage extension that includes the `clientAuth` and `serverAuth` values. +By default {{es}} uses mutual TLS (mTLS) to ensure the security of node-to-node transport connections within a cluster. Mutual TLS means that data is encrypted in transit, ensuring confidentiality and integrity, and also that both nodes in a connection must present a valid certificate to the other node when establishing the connection. Each {{es}} node requires that the certificate presented by the other node is issued by a certificate authority that it trusts for this purpose, ensuring that the nodes are authorized to establish this connection. The set of certificate authorities that a node trusts to issue certificates for transport connections is defined with settings in the `xpack.security.transport.ssl.*` namespace such as `xpack.security.transport.ssl.certificate_authorities` and `xpack.security.transport.ssl.truststore.path`. Certificates used for mTLS either must have no Extended Key Usage extension, or must have an Extended Key Usage extension that includes the `clientAuth` and `serverAuth` values. To realize the full benefits of the mTLS security model, obtain your transport certificates from a certificate authority that only issues certificates to {{es}} nodes which are permitted to connect to your cluster. Do not use a public certificate authority, nor an organization-wide private certificate authority, because such certificate authorities issue certificates to entities other than the {{es}} nodes which are permitted to connect to your cluster. Public certificate authorities generally issue certificates with an Extended Key Usage extension that omits the `clientAuth` value and therefore cannot be used for mTLS anyway. The recommended best practice is to use a different private certificate authority for each {{es}} cluster. From c8835f1b925f4c49b13fec74eb4e8b4d9d3a48f1 Mon Sep 17 00:00:00 2001 From: David Turner Date: Fri, 7 Nov 2025 10:24:47 +0000 Subject: [PATCH 10/13] Iter --- .../elasticsearch/configuration-reference/security-settings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/elasticsearch/configuration-reference/security-settings.md b/docs/reference/elasticsearch/configuration-reference/security-settings.md index ad8f028b3ea8a..f6105c8e72101 100644 --- a/docs/reference/elasticsearch/configuration-reference/security-settings.md +++ b/docs/reference/elasticsearch/configuration-reference/security-settings.md @@ -1919,7 +1919,7 @@ Transport connections between {{es}} nodes are security-critical and you must pr By default {{es}} uses mutual TLS (mTLS) to ensure the security of node-to-node transport connections within a cluster. Mutual TLS means that data is encrypted in transit, ensuring confidentiality and integrity, and also that both nodes in a connection must present a valid certificate to the other node when establishing the connection. Each {{es}} node requires that the certificate presented by the other node is issued by a certificate authority that it trusts for this purpose, ensuring that the nodes are authorized to establish this connection. The set of certificate authorities that a node trusts to issue certificates for transport connections is defined with settings in the `xpack.security.transport.ssl.*` namespace such as `xpack.security.transport.ssl.certificate_authorities` and `xpack.security.transport.ssl.truststore.path`. Certificates used for mTLS either must have no Extended Key Usage extension, or must have an Extended Key Usage extension that includes the `clientAuth` and `serverAuth` values. -To realize the full benefits of the mTLS security model, obtain your transport certificates from a certificate authority that only issues certificates to {{es}} nodes which are permitted to connect to your cluster. Do not use a public certificate authority, nor an organization-wide private certificate authority, because such certificate authorities issue certificates to entities other than the {{es}} nodes which are permitted to connect to your cluster. Public certificate authorities generally issue certificates with an Extended Key Usage extension that omits the `clientAuth` value and therefore cannot be used for mTLS anyway. The recommended best practice is to use a different private certificate authority for each {{es}} cluster. +When using mTLS you must obtain your transport certificates from a certificate authority that only issues certificates to {{es}} nodes which are permitted to connect to your cluster. Do not use a public certificate authority, nor an organization-wide private certificate authority, because such certificate authorities issue certificates to entities other than the {{es}} nodes which are permitted to connect to your cluster. Public certificate authorities generally issue certificates with an Extended Key Usage extension that omits the `clientAuth` value and therefore cannot be used for mTLS anyway. The recommended best practice is to use a different private certificate authority for each {{es}} cluster, and not to use these certificate authorities for any other purpose. ::::{warning} Anyone who can obtain a certificate from a certificate authority that your {{es}} cluster trusts for mTLS on transport connections will be able to use this certificate to establish a transport connection with a node in your cluster. A malicious actor with such a certificate may be able to use such a transport connection to invoke certain system-internal APIs, some of which may allow them to read or modify the data in your cluster. From 48a5928c29748ba6fd79472d7d9cd12bd73244fb Mon Sep 17 00:00:00 2001 From: David Turner Date: Fri, 7 Nov 2025 11:08:58 +0000 Subject: [PATCH 11/13] Call out common mistake --- .../elasticsearch/configuration-reference/security-settings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/elasticsearch/configuration-reference/security-settings.md b/docs/reference/elasticsearch/configuration-reference/security-settings.md index f6105c8e72101..5f976b2cc2c0f 100644 --- a/docs/reference/elasticsearch/configuration-reference/security-settings.md +++ b/docs/reference/elasticsearch/configuration-reference/security-settings.md @@ -1925,7 +1925,7 @@ When using mTLS you must obtain your transport certificates from a certificate a Anyone who can obtain a certificate from a certificate authority that your {{es}} cluster trusts for mTLS on transport connections will be able to use this certificate to establish a transport connection with a node in your cluster. A malicious actor with such a certificate may be able to use such a transport connection to invoke certain system-internal APIs, some of which may allow them to read or modify the data in your cluster. :::: -The security requirements for transport certificates (as defined by the `xpack.security.transport.ssl.*` settings) are significantly different from the security requirements for HTTP certificates (as defined by the `xpack.security.http.ssl.*` settings). HTTP connections do not generally use mTLS since HTTP has its own authentication mechanisms, so HTTP certificates do not usually need to include the `clientAuth` value in their Extended Key Usage extension. It often makes sense to obtain the nodes' HTTP certificates from a public certificate authority, or from an organization-wide private certificate authority. +The security requirements for transport certificates (as defined by the `xpack.security.transport.ssl.*` settings) are significantly different from the security requirements for HTTP certificates (as defined by the `xpack.security.http.ssl.*` settings). HTTP connections do not generally use mTLS since HTTP has its own authentication mechanisms, so HTTP certificates do not usually need to include the `clientAuth` value in their Extended Key Usage extension. It often makes sense to obtain the nodes' HTTP certificates from a public certificate authority, or from an organization-wide private certificate authority. It is almost always a mistake to use the same certificate for both HTTP and transport connections. If your environment has some other way to prevent unauthorized node-to-node connections, you may prefer not to use mTLS for transport connections. In this case, turn mTLS off in this context by setting `xpack.security.transport.ssl.client_authentication: none`. You may still use (non-mutual) TLS to ensure the confidentiality and integrity of node-to-node traffic by setting `xpack.security.transport.ssl.enabled: true`. If you are using non-mutual TLS for transport connections then you may use certificates issued by a public certificate authority, or an organization-wide private certificate authority, for your transport certificates. From f0d7f09f0cff9cf286d9bd7c9c4454eb17841f68 Mon Sep 17 00:00:00 2001 From: David Turner Date: Fri, 7 Nov 2025 11:22:57 +0000 Subject: [PATCH 12/13] Remove suggestion to use public CAs if mTLS disabled --- .../elasticsearch/configuration-reference/security-settings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/elasticsearch/configuration-reference/security-settings.md b/docs/reference/elasticsearch/configuration-reference/security-settings.md index 5f976b2cc2c0f..98fd2d074db34 100644 --- a/docs/reference/elasticsearch/configuration-reference/security-settings.md +++ b/docs/reference/elasticsearch/configuration-reference/security-settings.md @@ -1927,7 +1927,7 @@ Anyone who can obtain a certificate from a certificate authority that your {{es} The security requirements for transport certificates (as defined by the `xpack.security.transport.ssl.*` settings) are significantly different from the security requirements for HTTP certificates (as defined by the `xpack.security.http.ssl.*` settings). HTTP connections do not generally use mTLS since HTTP has its own authentication mechanisms, so HTTP certificates do not usually need to include the `clientAuth` value in their Extended Key Usage extension. It often makes sense to obtain the nodes' HTTP certificates from a public certificate authority, or from an organization-wide private certificate authority. It is almost always a mistake to use the same certificate for both HTTP and transport connections. -If your environment has some other way to prevent unauthorized node-to-node connections, you may prefer not to use mTLS for transport connections. In this case, turn mTLS off in this context by setting `xpack.security.transport.ssl.client_authentication: none`. You may still use (non-mutual) TLS to ensure the confidentiality and integrity of node-to-node traffic by setting `xpack.security.transport.ssl.enabled: true`. If you are using non-mutual TLS for transport connections then you may use certificates issued by a public certificate authority, or an organization-wide private certificate authority, for your transport certificates. +If your environment has some other way to prevent unauthorized node-to-node connections, you may prefer not to use mTLS for transport connections. In this case, turn mTLS off in this context by setting `xpack.security.transport.ssl.client_authentication: none`. You may still use (non-mutual) TLS to ensure the confidentiality and integrity of node-to-node traffic by setting `xpack.security.transport.ssl.enabled: true`. If you are using non-mutual TLS for transport connections then your transport certificates do not require an Extended Key Usage extension which includes the `clientAuth` value. ::::{warning} If you turn off mTLS by setting `xpack.security.transport.ssl.client_authentication` to `optional` or `none` then anyone with network access to a node in your {{es}} cluster will be able to establish a transport connection with that node. A malicious actor with this access may be able to use such a transport connection to invoke certain system-internal APIs, some of which may allow them to read or modify the data in your cluster. Use mTLS to protect your node-to-node transport connections unless you are absolutely certain that unauthorized network access to these nodes cannot occur. From 4b44f254821035adcb4b06b3e889433922ba7e8e Mon Sep 17 00:00:00 2001 From: David Turner Date: Fri, 7 Nov 2025 11:24:02 +0000 Subject: [PATCH 13/13] Context is overloaded --- .../elasticsearch/configuration-reference/security-settings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/elasticsearch/configuration-reference/security-settings.md b/docs/reference/elasticsearch/configuration-reference/security-settings.md index 98fd2d074db34..337f6921a4025 100644 --- a/docs/reference/elasticsearch/configuration-reference/security-settings.md +++ b/docs/reference/elasticsearch/configuration-reference/security-settings.md @@ -1927,7 +1927,7 @@ Anyone who can obtain a certificate from a certificate authority that your {{es} The security requirements for transport certificates (as defined by the `xpack.security.transport.ssl.*` settings) are significantly different from the security requirements for HTTP certificates (as defined by the `xpack.security.http.ssl.*` settings). HTTP connections do not generally use mTLS since HTTP has its own authentication mechanisms, so HTTP certificates do not usually need to include the `clientAuth` value in their Extended Key Usage extension. It often makes sense to obtain the nodes' HTTP certificates from a public certificate authority, or from an organization-wide private certificate authority. It is almost always a mistake to use the same certificate for both HTTP and transport connections. -If your environment has some other way to prevent unauthorized node-to-node connections, you may prefer not to use mTLS for transport connections. In this case, turn mTLS off in this context by setting `xpack.security.transport.ssl.client_authentication: none`. You may still use (non-mutual) TLS to ensure the confidentiality and integrity of node-to-node traffic by setting `xpack.security.transport.ssl.enabled: true`. If you are using non-mutual TLS for transport connections then your transport certificates do not require an Extended Key Usage extension which includes the `clientAuth` value. +If your environment has some other way to prevent unauthorized node-to-node connections, you may prefer not to use mTLS for transport connections. In this case, turn off mTLS for transport connections by setting `xpack.security.transport.ssl.client_authentication: none`. You may still use (non-mutual) TLS to ensure the confidentiality and integrity of node-to-node traffic by setting `xpack.security.transport.ssl.enabled: true`. If you are using non-mutual TLS for transport connections then your transport certificates do not require an Extended Key Usage extension which includes the `clientAuth` value. ::::{warning} If you turn off mTLS by setting `xpack.security.transport.ssl.client_authentication` to `optional` or `none` then anyone with network access to a node in your {{es}} cluster will be able to establish a transport connection with that node. A malicious actor with this access may be able to use such a transport connection to invoke certain system-internal APIs, some of which may allow them to read or modify the data in your cluster. Use mTLS to protect your node-to-node transport connections unless you are absolutely certain that unauthorized network access to these nodes cannot occur.