From 4ef3fbbdd6c19bd65e1c09b78200205810ad2e55 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Thu, 13 Nov 2025 11:59:30 -0500 Subject: [PATCH 01/18] dave-content --- .../security/self-tls-considerations.md | 75 +++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 deploy-manage/security/self-tls-considerations.md diff --git a/deploy-manage/security/self-tls-considerations.md b/deploy-manage/security/self-tls-considerations.md new file mode 100644 index 0000000000..14c5425c6d --- /dev/null +++ b/deploy-manage/security/self-tls-considerations.md @@ -0,0 +1,75 @@ +--- +navigation_title: Considerations +applies_to: + deployment: + self: + eck: +products: + - id: elasticsearch +navigation_title: External CA considerations +--- + +# Considerations for using an external CA for transport layer security + +::::{important} +Transport connections between {{es}} nodes are security-critical. Malicious actors who can observe, interfere with, or establish these connections may be able to read or modify cluster data through system-internal APIs. +:::: + +## How mutual TLS protects transport connections + +By default, {{es}} uses mutual TLS (mTLS) for node-to-node transport connections. This ensures: + +- **Encryption**: Data is encrypted in transit for confidentiality and integrity +- **Authentication**: Both nodes must present valid certificates when connecting +- **Authorization**: Certificates must be issued by a trusted certificate authority + +Configure trusted certificate authorities using settings like `xpack.security.transport.ssl.certificate_authorities` or `xpack.security.transport.ssl.truststore.path`. + +## Certificate authority requirements + +::::{warning} +Anyone with a certificate from a trusted CA can establish transport connections to your cluster and potentially access or modify data. +:::: + +Use a dedicated private certificate authority for each {{es}} cluster. **Do not use**: + +- Public certificate authorities +- Organization-wide private certificate authorities +- CAs shared with other applications + +These broader CAs issue certificates to entities beyond your authorized {{es}} nodes, creating security risks. + +## Certificate requirements + +Transport certificates must either: +- Have no Extended Key Usage (EKU) extension, or +- Include both `clientAuth` and `serverAuth` in the EKU extension + +Public CAs typically omit `clientAuth`, making their certificates unsuitable for mTLS. + +## HTTP versus transport certificates + +**Do not use the same certificate for both HTTP and transport connections.** They have different security requirements: + +- **Transport certificates** (`xpack.security.transport.ssl.*`): Require mTLS and must include `clientAuth` in the EKU extension +- **HTTP certificates** (`xpack.security.http.ssl.*`): Use HTTP authentication mechanisms and typically don't need `clientAuth` + +HTTP certificates can often come from public or organization-wide CAs, while transport certificates should always use a cluster-specific private CA. + +## Disabling mutual TLS + +If your environment prevents unauthorized node-to-node connections through other means, you can disable mTLS: + +```yaml +xpack.security.transport.ssl.client_authentication: none +``` + +You can still use non-mutual TLS for encryption: + +```yaml +xpack.security.transport.ssl.enabled: true +``` + +::::{warning} +Disabling mTLS allows anyone with network access to establish transport connections. Only do this if you're absolutely certain unauthorized network access cannot occur. +:::: \ No newline at end of file From 3f5b4332c4f49a2bb2139d509be7f7073e5b582e Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Thu, 13 Nov 2025 12:45:01 -0500 Subject: [PATCH 02/18] add new considerations page, warnings to relevant procedures --- .../security/_snippets/own-ca-warning.md | 5 ++ deploy-manage/security/different-ca.md | 4 ++ .../security/k8s-transport-settings.md | 6 ++ deploy-manage/security/same-ca.md | 3 + .../security/secure-cluster-communications.md | 21 ++++--- .../security/self-tls-considerations.md | 60 ++++--------------- .../security/set-up-basic-security.md | 8 +++ deploy-manage/toc.yml | 1 + 8 files changed, 52 insertions(+), 56 deletions(-) create mode 100644 deploy-manage/security/_snippets/own-ca-warning.md diff --git a/deploy-manage/security/_snippets/own-ca-warning.md b/deploy-manage/security/_snippets/own-ca-warning.md new file mode 100644 index 0000000000..62211f9742 --- /dev/null +++ b/deploy-manage/security/_snippets/own-ca-warning.md @@ -0,0 +1,5 @@ +:::{warning} +Transport connections between {{es}} nodes are security-critical and you must protect them carefully. Malicious actors who can observe or interfere with node-to-node transport traffic can read or modify cluster data. A malicious actor who can establish a transport connection might be able to invoke system-internal APIs, including APIs that read or modify cluster data. + +If you choose to issue node transport certificates using third-party tools, then carefully review [](/deploy-manage/security/self-tls-considerations.md) to ensure that the certificates that you provide meet the security requirements for transport connections. +::: \ No newline at end of file diff --git a/deploy-manage/security/different-ca.md b/deploy-manage/security/different-ca.md index 101f0d62cb..1a672313eb 100644 --- a/deploy-manage/security/different-ca.md +++ b/deploy-manage/security/different-ca.md @@ -15,6 +15,10 @@ products: 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. +:::{include} ./_snippets/own-ca-warning.md +::: + + ## Generate a new certificate for the transport layer [node-certs-different-transport] 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!). diff --git a/deploy-manage/security/k8s-transport-settings.md b/deploy-manage/security/k8s-transport-settings.md index 9f21f518bb..44e70d470d 100644 --- a/deploy-manage/security/k8s-transport-settings.md +++ b/deploy-manage/security/k8s-transport-settings.md @@ -75,6 +75,12 @@ spec: ## Issue node transport certificates with third-party tools [k8s-transport-third-party-tools] +:::{warning} +Transport connections between {{es}} nodes are security-critical and you must protect them carefully. Malicious actors who can observe or interfere with node-to-node transport traffic can read or modify cluster data. A malicious actor who can establish a transport connection might be able to invoke system-internal APIs, including APIs that read or modify cluster data. + +If you choose to issue node transport certificates using third-party tools, then carefully review [](/deploy-manage/security/self-tls-considerations.md) to ensure that the certificates that you provide meet the security requirements for transport connections. +::: + When following the instructions in [Configure a custom Certificate Authority](#k8s-transport-ca) the issuance of certificates is orchestrated by the ECK operator and the operator needs access to the CAs private key. If this is undesirable it is also possible to configure node transport certificates without involving the ECK operator. The following two pre-requisites apply: 1. The tooling used must be able to issue individual certificates for each {{es}} node and dynamically add or remove certificates as the cluster scales up and down. diff --git a/deploy-manage/security/same-ca.md b/deploy-manage/security/same-ca.md index a8cdef7290..522b485bbc 100644 --- a/deploy-manage/security/same-ca.md +++ b/deploy-manage/security/same-ca.md @@ -22,6 +22,9 @@ You don’t have to restart each node, but doing so forces new TLS connections a 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. +:::{include} ./_snippets/own-ca-warning.md +::: + ::::{important} :name: cert-password-updates diff --git a/deploy-manage/security/secure-cluster-communications.md b/deploy-manage/security/secure-cluster-communications.md index c76140a0cb..d1eb532ff4 100644 --- a/deploy-manage/security/secure-cluster-communications.md +++ b/deploy-manage/security/secure-cluster-communications.md @@ -57,36 +57,43 @@ Securing this layer prevents unauthorized nodes from joining your cluster and pr The way that transport layer security is managed depends on your deployment type: -::::{tab-set} +:::::{tab-set} :group: deployments -:::{tab-item} ECH and Serverless +::::{tab-item} ECH and Serverless :sync: ech {{es}} transport security is fully managed by Elastic, and no configuration is required. -::: +:::: -:::{tab-item} ECE +::::{admonition}{tab-item} ECE :sync: ece {{es}} transport security is fully managed by {{ece}} platform, and no configuration is required. -::: +:::: -:::{tab-item} ECK +::::{tab-item} ECK :sync: eck :::{include} ./_snippets/eck-transport.md ::: +:::{include} ./_snippets/own-ca-warning.md ::: -:::{tab-item} Self-managed +:::: + +::::{tab-item} Self-managed :sync: self {{es}} transport security can be [automatically configured](self-auto-setup.md), or manually set up by following the steps in [](set-up-basic-security.md). For additional TLS configuration options, refer to [](./self-tls.md). + +:::{include} ./_snippets/own-ca-warning.md ::: :::: +::::: + ### HTTP layer security [encrypt-http-communication] The HTTP layer includes the service endpoints exposed by both {{es}} and {{kib}}, supporting communications such as REST API requests, browser access to {{kib}}, and {{kib}}’s own traffic to {{es}}. Securing these endpoints helps prevent unauthorized access and protects sensitive data in transit. diff --git a/deploy-manage/security/self-tls-considerations.md b/deploy-manage/security/self-tls-considerations.md index 14c5425c6d..e57756d5ee 100644 --- a/deploy-manage/security/self-tls-considerations.md +++ b/deploy-manage/security/self-tls-considerations.md @@ -11,65 +11,27 @@ navigation_title: External CA considerations # Considerations for using an external CA for transport layer security -::::{important} -Transport connections between {{es}} nodes are security-critical. Malicious actors who can observe, interfere with, or establish these connections may be able to read or modify cluster data through system-internal APIs. -:::: - -## How mutual TLS protects transport connections - -By default, {{es}} uses mutual TLS (mTLS) for node-to-node transport connections. This ensures: - -- **Encryption**: Data is encrypted in transit for confidentiality and integrity -- **Authentication**: Both nodes must present valid certificates when connecting -- **Authorization**: Certificates must be issued by a trusted certificate authority - -Configure trusted certificate authorities using settings like `xpack.security.transport.ssl.certificate_authorities` or `xpack.security.transport.ssl.truststore.path`. - -## Certificate authority requirements +By default, {{es}} uses mutual TLS (mTLS) to secure node-to-node transport connections within a cluster. With mTLS, data is encrypted in transit and both nodes must present valid certificates when connecting. Each node requires that certificates be issued by a trusted certificate authority, ensuring that only authorized nodes can connect. Configure trusted certificate authorities using settings in the [`xpack.security.transport.ssl.*`](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#transport-tls-ssl-settings) namespace, such as `xpack.security.transport.ssl.certificate_authorities` and `xpack.security.transport.ssl.truststore.path`. ::::{warning} -Anyone with a certificate from a trusted CA can establish transport connections to your cluster and potentially access or modify data. +Transport connections between {{es}} nodes are security-critical and you must protect them carefully. Malicious actors who can observe or interfere with node-to-node transport traffic can read or modify cluster data. A malicious actor who can establish a transport connection might be able to invoke system-internal APIs, including APIs that read or modify cluster data. :::: -Use a dedicated private certificate authority for each {{es}} cluster. **Do not use**: - -- Public certificate authorities -- Organization-wide private certificate authorities -- CAs shared with other applications - -These broader CAs issue certificates to entities beyond your authorized {{es}} nodes, creating security risks. - -## Certificate requirements - -Transport certificates must either: -- Have no Extended Key Usage (EKU) extension, or -- Include both `clientAuth` and `serverAuth` in the EKU extension - -Public CAs typically omit `clientAuth`, making their certificates unsuitable for mTLS. - -## HTTP versus transport certificates - -**Do not use the same certificate for both HTTP and transport connections.** They have different security requirements: - -- **Transport certificates** (`xpack.security.transport.ssl.*`): Require mTLS and must include `clientAuth` in the EKU extension -- **HTTP certificates** (`xpack.security.http.ssl.*`): Use HTTP authentication mechanisms and typically don't need `clientAuth` +## External CA mTLS transport certificate requirements -HTTP certificates can often come from public or organization-wide CAs, while transport certificates should always use a cluster-specific private CA. +Obtain your transport certificates from a certificate authority that only issues certificates to {{es}} nodes permitted to connect to your cluster. Do not use a public certificate authority or an organization-wide private certificate authority, because these issue certificates to entities beyond your authorized cluster nodes. The recommended practice is to use a dedicated private certificate authority for each {{es}} cluster. -## Disabling mutual TLS +Certificates used for mTLS must either have no Extended Key Usage extension, or include both `clientAuth` and `serverAuth` values in the extension. Public certificate authorities typically omit the `clientAuth` value in the Extended Key Usage extension, making them unsuitable for mTLS. -If your environment prevents unauthorized node-to-node connections through other means, you can disable mTLS: +### Transport certificates vs. HTTP certificates -```yaml -xpack.security.transport.ssl.client_authentication: none -``` +Transport certificates ([`xpack.security.transport.ssl.*`](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#transport-tls-ssl-settings) settings) have different security requirements than HTTP certificates ([`xpack.security.http.ssl.*`]((elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#http-tls-ssl-settings)) settings). HTTP connections don't typically use mTLS because HTTP has its own authentication mechanisms, so HTTP certificates usually don't need to include the `clientAuth` value in their Extended Key Usage extension. HTTP certificates can come from public or organization-wide certificate authorities, while transport certificates should use a cluster-specific private CA. In most cases, you should not use the same certificate for both HTTP and transport connections. -You can still use non-mutual TLS for encryption: +## Turning off mTLS for transport connections -```yaml -xpack.security.transport.ssl.enabled: true -``` +If your environment has some other way to prevent unauthorized node-to-node connections, you might prefer not to use mTLS for transport connections. In this case, you can disable mTLS by setting `xpack.security.transport.ssl.client_authentication: none`. You can still use non-mutual TLS for encryption by setting `xpack.security.transport.ssl.enabled: true`. With non-mutual TLS, transport certificates don't require the `clientAuth` value in the Extended Key Usage extension. ::::{warning} -Disabling mTLS allows anyone with network access to establish transport connections. Only do this if you're absolutely certain unauthorized network access cannot occur. +Turning off mTLS by setting `xpack.security.transport.ssl.client_authentication` to `optional` or `none` allows anyone with network access to establish transport connections. Malicious actors can use these connections to invoke system-internal APIs that may read or modify cluster data. Use mTLS to +protect your node-to-node transport connections unless you are absolutely certain that unauthorized network access to these nodes cannot occur. :::: \ 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 0da5d5abb3..1422d89312 100644 --- a/deploy-manage/security/set-up-basic-security.md +++ b/deploy-manage/security/set-up-basic-security.md @@ -28,6 +28,14 @@ In this guide, you will learn how to: Refer to [Transport TLS/SSL settings](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#transport-tls-ssl-settings) for the complete list of available settings in {{es}}. +## Considerations for using an external CA + +You might choose to use an external CA to generate transport certificates for node-to-node connections. + +Transport connections between {{es}} nodes are security-critical and you must protect them carefully. Malicious actors who can observe or interfere with node-to-node transport traffic can read or modify cluster data. A malicious actor who can establish a transport connection might be able to invoke system-internal APIs, including APIs that read or modify cluster data. + +Carefully review [](/deploy-manage/security/self-tls-considerations.md) to ensure that the certificates that you provide meet the security requirements for transport connections. + ## Generate the certificate authority [generate-certificates] You can add as many nodes as you want in a cluster but they must be able to communicate with each other. The communication between nodes in a cluster is handled by the transport module. To secure your cluster, you must ensure that internode communications are encrypted and verified, which is achieved with mutual TLS. diff --git a/deploy-manage/toc.yml b/deploy-manage/toc.yml index 8b4773bbf1..f34791f7bc 100644 --- a/deploy-manage/toc.yml +++ b/deploy-manage/toc.yml @@ -488,6 +488,7 @@ toc: children: - file: security/k8s-https-settings.md - file: security/k8s-transport-settings.md + - file: security/self-tls-considerations.md - file: security/network-security.md children: - file: security/network-security-policies.md From c401bfa49c0b2800ee2a54ab9c8fe3fa0f858f06 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Thu, 13 Nov 2025 12:54:50 -0500 Subject: [PATCH 03/18] too many brackets --- deploy-manage/security/self-tls-considerations.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/deploy-manage/security/self-tls-considerations.md b/deploy-manage/security/self-tls-considerations.md index e57756d5ee..bfac2dd52d 100644 --- a/deploy-manage/security/self-tls-considerations.md +++ b/deploy-manage/security/self-tls-considerations.md @@ -25,9 +25,9 @@ Certificates used for mTLS must either have no Extended Key Usage extension, or ### Transport certificates vs. HTTP certificates -Transport certificates ([`xpack.security.transport.ssl.*`](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#transport-tls-ssl-settings) settings) have different security requirements than HTTP certificates ([`xpack.security.http.ssl.*`]((elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#http-tls-ssl-settings)) settings). HTTP connections don't typically use mTLS because HTTP has its own authentication mechanisms, so HTTP certificates usually don't need to include the `clientAuth` value in their Extended Key Usage extension. HTTP certificates can come from public or organization-wide certificate authorities, while transport certificates should use a cluster-specific private CA. In most cases, you should not use the same certificate for both HTTP and transport connections. +Transport certificates ([`xpack.security.transport.ssl.*`](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#transport-tls-ssl-settings) settings) have different security requirements than HTTP certificates ([`xpack.security.http.ssl.*`](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#http-tls-ssl-settings) settings). HTTP connections don't typically use mTLS because HTTP has its own authentication mechanisms, so HTTP certificates usually don't need to include the `clientAuth` value in their Extended Key Usage extension. HTTP certificates can come from public or organization-wide certificate authorities, while transport certificates should use a cluster-specific private CA. In most cases, you should not use the same certificate for both HTTP and transport connections. -## Turning off mTLS for transport connections +## Turning off mTLS for transport connections [turn-off-mtls] If your environment has some other way to prevent unauthorized node-to-node connections, you might prefer not to use mTLS for transport connections. In this case, you can disable mTLS by setting `xpack.security.transport.ssl.client_authentication: none`. You can still use non-mutual TLS for encryption by setting `xpack.security.transport.ssl.enabled: true`. With non-mutual TLS, transport certificates don't require the `clientAuth` value in the Extended Key Usage extension. From b94310e9c5c2fe2d941bb54054ee68ee714b76d1 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Thu, 13 Nov 2025 13:03:33 -0500 Subject: [PATCH 04/18] polish --- deploy-manage/security/self-tls-considerations.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/deploy-manage/security/self-tls-considerations.md b/deploy-manage/security/self-tls-considerations.md index bfac2dd52d..756a804602 100644 --- a/deploy-manage/security/self-tls-considerations.md +++ b/deploy-manage/security/self-tls-considerations.md @@ -11,7 +11,7 @@ navigation_title: External CA considerations # Considerations for using an external CA for transport layer security -By default, {{es}} uses mutual TLS (mTLS) to secure node-to-node transport connections within a cluster. With mTLS, data is encrypted in transit and both nodes must present valid certificates when connecting. Each node requires that certificates be issued by a trusted certificate authority, ensuring that only authorized nodes can connect. Configure trusted certificate authorities using settings in the [`xpack.security.transport.ssl.*`](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#transport-tls-ssl-settings) namespace, such as `xpack.security.transport.ssl.certificate_authorities` and `xpack.security.transport.ssl.truststore.path`. +By default, {{es}} uses mutual TLS (mTLS) to secure node-to-node transport connections. With mTLS, data is encrypted in transit and both nodes must present valid certificates when connecting. Each node requires that certificates be issued by a trusted certificate authority, ensuring that only authorized nodes can connect. Configure trusted certificate authorities using settings in the [`xpack.security.transport.ssl.*`](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#transport-tls-ssl-settings) namespace, such as `xpack.security.transport.ssl.certificate_authorities` and `xpack.security.transport.ssl.truststore.path`. ::::{warning} Transport connections between {{es}} nodes are security-critical and you must protect them carefully. Malicious actors who can observe or interfere with node-to-node transport traffic can read or modify cluster data. A malicious actor who can establish a transport connection might be able to invoke system-internal APIs, including APIs that read or modify cluster data. @@ -19,7 +19,7 @@ Transport connections between {{es}} nodes are security-critical and you must pr ## External CA mTLS transport certificate requirements -Obtain your transport certificates from a certificate authority that only issues certificates to {{es}} nodes permitted to connect to your cluster. Do not use a public certificate authority or an organization-wide private certificate authority, because these issue certificates to entities beyond your authorized cluster nodes. The recommended practice is to use a dedicated private certificate authority for each {{es}} cluster. +Obtain your transport certificates from a certificate authority that only issues certificates to {{es}} nodes permitted to connect to your cluster. Do not use a public certificate authority or an organization-wide private certificate authority, because these issue certificates to entities beyond your authorized cluster nodes. Use a dedicated private certificate authority for each {{es}} cluster. Certificates used for mTLS must either have no Extended Key Usage extension, or include both `clientAuth` and `serverAuth` values in the extension. Public certificate authorities typically omit the `clientAuth` value in the Extended Key Usage extension, making them unsuitable for mTLS. @@ -29,7 +29,7 @@ Transport certificates ([`xpack.security.transport.ssl.*`](elasticsearch://refer ## Turning off mTLS for transport connections [turn-off-mtls] -If your environment has some other way to prevent unauthorized node-to-node connections, you might prefer not to use mTLS for transport connections. In this case, you can disable mTLS by setting `xpack.security.transport.ssl.client_authentication: none`. You can still use non-mutual TLS for encryption by setting `xpack.security.transport.ssl.enabled: true`. With non-mutual TLS, transport certificates don't require the `clientAuth` value in the Extended Key Usage extension. +If your environment has some other way to prevent unauthorized node-to-node connections, you can disable mTLS by setting `xpack.security.transport.ssl.client_authentication: none`. You can still use non-mutual TLS for encryption by setting `xpack.security.transport.ssl.enabled: true`. With non-mutual TLS, transport certificates don't require the `clientAuth` value in the Extended Key Usage extension. ::::{warning} Turning off mTLS by setting `xpack.security.transport.ssl.client_authentication` to `optional` or `none` allows anyone with network access to establish transport connections. Malicious actors can use these connections to invoke system-internal APIs that may read or modify cluster data. Use mTLS to From 60e11e07dc7b9a9b03408d4b72eb87724744f48e Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Thu, 13 Nov 2025 13:07:18 -0500 Subject: [PATCH 05/18] polish 2 --- deploy-manage/security/self-tls-considerations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/deploy-manage/security/self-tls-considerations.md b/deploy-manage/security/self-tls-considerations.md index 756a804602..b8df017067 100644 --- a/deploy-manage/security/self-tls-considerations.md +++ b/deploy-manage/security/self-tls-considerations.md @@ -25,7 +25,7 @@ Certificates used for mTLS must either have no Extended Key Usage extension, or ### Transport certificates vs. HTTP certificates -Transport certificates ([`xpack.security.transport.ssl.*`](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#transport-tls-ssl-settings) settings) have different security requirements than HTTP certificates ([`xpack.security.http.ssl.*`](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#http-tls-ssl-settings) settings). HTTP connections don't typically use mTLS because HTTP has its own authentication mechanisms, so HTTP certificates usually don't need to include the `clientAuth` value in their Extended Key Usage extension. HTTP certificates can come from public or organization-wide certificate authorities, while transport certificates should use a cluster-specific private CA. In most cases, you should not use the same certificate for both HTTP and transport connections. +Transport certificates have different security requirements than [HTTP certificates](/deploy-manage/security/secure-cluster-communications.md#encrypt-http-communication). HTTP connections don't typically use mTLS because HTTP has its own authentication mechanisms. Because of this, HTTP certificates usually don't need to include the `clientAuth` value in their Extended Key Usage extension. HTTP certificates can come from public or organization-wide certificate authorities, while transport certificates should use a cluster-specific private CA. In most cases, you should not use the same certificate for both HTTP and transport connections. ## Turning off mTLS for transport connections [turn-off-mtls] From 74894f34960040bb14f3d626f6ba5bd826b2b20f Mon Sep 17 00:00:00 2001 From: shainaraskas <58563081+shainaraskas@users.noreply.github.com> Date: Thu, 13 Nov 2025 14:18:28 -0500 Subject: [PATCH 06/18] Update deploy-manage/security/self-tls-considerations.md --- deploy-manage/security/self-tls-considerations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/deploy-manage/security/self-tls-considerations.md b/deploy-manage/security/self-tls-considerations.md index b8df017067..18cb0a554a 100644 --- a/deploy-manage/security/self-tls-considerations.md +++ b/deploy-manage/security/self-tls-considerations.md @@ -11,7 +11,7 @@ navigation_title: External CA considerations # Considerations for using an external CA for transport layer security -By default, {{es}} uses mutual TLS (mTLS) to secure node-to-node transport connections. With mTLS, data is encrypted in transit and both nodes must present valid certificates when connecting. Each node requires that certificates be issued by a trusted certificate authority, ensuring that only authorized nodes can connect. Configure trusted certificate authorities using settings in the [`xpack.security.transport.ssl.*`](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#transport-tls-ssl-settings) namespace, such as `xpack.security.transport.ssl.certificate_authorities` and `xpack.security.transport.ssl.truststore.path`. +By default, {{es}} uses mutual TLS (mTLS) to secure node-to-node transport connections. 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 node requires that certificates be issued by a trusted certificate authority, ensuring that only authorized nodes can connect. Configure trusted certificate authorities using settings in the [`xpack.security.transport.ssl.*`](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#transport-tls-ssl-settings) namespace, such as `xpack.security.transport.ssl.certificate_authorities` and `xpack.security.transport.ssl.truststore.path`. ::::{warning} Transport connections between {{es}} nodes are security-critical and you must protect them carefully. Malicious actors who can observe or interfere with node-to-node transport traffic can read or modify cluster data. A malicious actor who can establish a transport connection might be able to invoke system-internal APIs, including APIs that read or modify cluster data. From 141c98d6bd545ad5c93b379344452b8880c85264 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Thu, 13 Nov 2025 14:21:18 -0500 Subject: [PATCH 07/18] dave feedback --- deploy-manage/security/k8s-transport-settings.md | 5 +---- deploy-manage/security/self-tls-considerations.md | 4 ++-- deploy-manage/security/set-up-basic-security.md | 2 +- 3 files changed, 4 insertions(+), 7 deletions(-) diff --git a/deploy-manage/security/k8s-transport-settings.md b/deploy-manage/security/k8s-transport-settings.md index 44e70d470d..6106c0a77e 100644 --- a/deploy-manage/security/k8s-transport-settings.md +++ b/deploy-manage/security/k8s-transport-settings.md @@ -75,10 +75,7 @@ spec: ## Issue node transport certificates with third-party tools [k8s-transport-third-party-tools] -:::{warning} -Transport connections between {{es}} nodes are security-critical and you must protect them carefully. Malicious actors who can observe or interfere with node-to-node transport traffic can read or modify cluster data. A malicious actor who can establish a transport connection might be able to invoke system-internal APIs, including APIs that read or modify cluster data. - -If you choose to issue node transport certificates using third-party tools, then carefully review [](/deploy-manage/security/self-tls-considerations.md) to ensure that the certificates that you provide meet the security requirements for transport connections. +:::{include} ./_snippets/own-ca-warning.md ::: When following the instructions in [Configure a custom Certificate Authority](#k8s-transport-ca) the issuance of certificates is orchestrated by the ECK operator and the operator needs access to the CAs private key. If this is undesirable it is also possible to configure node transport certificates without involving the ECK operator. The following two pre-requisites apply: diff --git a/deploy-manage/security/self-tls-considerations.md b/deploy-manage/security/self-tls-considerations.md index b8df017067..8b335f945c 100644 --- a/deploy-manage/security/self-tls-considerations.md +++ b/deploy-manage/security/self-tls-considerations.md @@ -14,7 +14,7 @@ navigation_title: External CA considerations By default, {{es}} uses mutual TLS (mTLS) to secure node-to-node transport connections. With mTLS, data is encrypted in transit and both nodes must present valid certificates when connecting. Each node requires that certificates be issued by a trusted certificate authority, ensuring that only authorized nodes can connect. Configure trusted certificate authorities using settings in the [`xpack.security.transport.ssl.*`](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#transport-tls-ssl-settings) namespace, such as `xpack.security.transport.ssl.certificate_authorities` and `xpack.security.transport.ssl.truststore.path`. ::::{warning} -Transport connections between {{es}} nodes are security-critical and you must protect them carefully. Malicious actors who can observe or interfere with node-to-node transport traffic can read or modify cluster data. A malicious actor who can establish a transport connection might be able to invoke system-internal APIs, including APIs that read or modify cluster data. +Transport connections between {{es}} nodes are security-critical and you must protect them carefully. Malicious actors who can observe or interfere with unencrypted node-to-node transport traffic can read or modify cluster data. A malicious actor who can establish a transport connection might be able to invoke system-internal APIs, including APIs that read or modify cluster data. :::: ## External CA mTLS transport certificate requirements @@ -29,7 +29,7 @@ Transport certificates have different security requirements than [HTTP certifica ## Turning off mTLS for transport connections [turn-off-mtls] -If your environment has some other way to prevent unauthorized node-to-node connections, you can disable mTLS by setting `xpack.security.transport.ssl.client_authentication: none`. You can still use non-mutual TLS for encryption by setting `xpack.security.transport.ssl.enabled: true`. With non-mutual TLS, transport certificates don't require the `clientAuth` value in the Extended Key Usage extension. +If your environment has some other way to prevent unauthorized node-to-node connections, you can disable mTLS by setting `xpack.security.transport.ssl.client_authentication: none`. You can still use non-mutual TLS to ensure the confidentiality and integrity of node-to-node traffic by setting `xpack.security.transport.ssl.enabled: true`. With non-mutual TLS, transport certificates don't require the `clientAuth` value in the Extended Key Usage extension. ::::{warning} Turning off mTLS by setting `xpack.security.transport.ssl.client_authentication` to `optional` or `none` allows anyone with network access to establish transport connections. Malicious actors can use these connections to invoke system-internal APIs that may read or modify cluster data. Use mTLS to diff --git a/deploy-manage/security/set-up-basic-security.md b/deploy-manage/security/set-up-basic-security.md index 1422d89312..e8f20f795d 100644 --- a/deploy-manage/security/set-up-basic-security.md +++ b/deploy-manage/security/set-up-basic-security.md @@ -32,7 +32,7 @@ Refer to [Transport TLS/SSL settings](elasticsearch://reference/elasticsearch/co You might choose to use an external CA to generate transport certificates for node-to-node connections. -Transport connections between {{es}} nodes are security-critical and you must protect them carefully. Malicious actors who can observe or interfere with node-to-node transport traffic can read or modify cluster data. A malicious actor who can establish a transport connection might be able to invoke system-internal APIs, including APIs that read or modify cluster data. +Transport connections between {{es}} nodes are security-critical and you must protect them carefully. Malicious actors who can observe or interfere with unencrypted node-to-node transport traffic can read or modify cluster data. A malicious actor who can establish a transport connection might be able to invoke system-internal APIs, including APIs that read or modify cluster data. Carefully review [](/deploy-manage/security/self-tls-considerations.md) to ensure that the certificates that you provide meet the security requirements for transport connections. From d6ecddf21224c06f3a677d10a478853650fa95e6 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Thu, 13 Nov 2025 14:48:00 -0500 Subject: [PATCH 08/18] basic security tutorial now mostly works for private/3P CA case --- .../security/self-tls-considerations.md | 6 +-- .../security/set-up-basic-security.md | 43 ++++++++++++------- 2 files changed, 31 insertions(+), 18 deletions(-) diff --git a/deploy-manage/security/self-tls-considerations.md b/deploy-manage/security/self-tls-considerations.md index 061aa6fe84..896b4f2b42 100644 --- a/deploy-manage/security/self-tls-considerations.md +++ b/deploy-manage/security/self-tls-considerations.md @@ -6,10 +6,10 @@ applies_to: eck: products: - id: elasticsearch -navigation_title: External CA considerations +navigation_title: Private or 3P CA considerations --- -# Considerations for using an external CA for transport layer security +# Considerations for using an private or third-party CA for transport layer security By default, {{es}} uses mutual TLS (mTLS) to secure node-to-node transport connections. 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 node requires that certificates be issued by a trusted certificate authority, ensuring that only authorized nodes can connect. Configure trusted certificate authorities using settings in the [`xpack.security.transport.ssl.*`](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#transport-tls-ssl-settings) namespace, such as `xpack.security.transport.ssl.certificate_authorities` and `xpack.security.transport.ssl.truststore.path`. @@ -17,7 +17,7 @@ By default, {{es}} uses mutual TLS (mTLS) to secure node-to-node transport conne Transport connections between {{es}} nodes are security-critical and you must protect them carefully. Malicious actors who can observe or interfere with unencrypted node-to-node transport traffic can read or modify cluster data. A malicious actor who can establish a transport connection might be able to invoke system-internal APIs, including APIs that read or modify cluster data. :::: -## External CA mTLS transport certificate requirements +## mTLS transport certificate requirements for private or third-party CAs Obtain your transport certificates from a certificate authority that only issues certificates to {{es}} nodes permitted to connect to your cluster. Do not use a public certificate authority or an organization-wide private certificate authority, because these issue certificates to entities beyond your authorized cluster nodes. Use a dedicated private certificate authority for each {{es}} cluster. diff --git a/deploy-manage/security/set-up-basic-security.md b/deploy-manage/security/set-up-basic-security.md index e8f20f795d..ac6c41595d 100644 --- a/deploy-manage/security/set-up-basic-security.md +++ b/deploy-manage/security/set-up-basic-security.md @@ -17,34 +17,45 @@ Configuring TLS between nodes is the basic security setup to prevent unauthorize This document focuses on the **manual configuration** of TLS for [{{es}} transport protocol](./secure-cluster-communications.md#encrypt-internode-communication) in self-managed environments. Use this approach if you want to provide your own TLS certificates, generate them with Elastic’s tools, or have full control over the configuration. Alternatively, {{es}} can [automatically generate and configure HTTPS certificates](./self-auto-setup.md) for you. +In this guide, you will learn how to: + +* [Either provide or generate security certificates](#obtain-certificates). +* [Configure your {{es}} nodes to use the generated certificate for the transport layer](#encrypt-internode-communication). + +Refer to [Transport TLS/SSL settings](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#transport-tls-ssl-settings) for the complete list of available settings in {{es}}. + ::::{note} For other deployment types, such as {{ech}}, {{ece}}, or {{eck}}, refer to [](./secure-cluster-communications.md). :::: -In this guide, you will learn how to: +## Obtain certificates -* [Generate a Certificate Authority (CA) and a server certificate using the `elasticsearch-certutil` tool](#generate-certificates). -* [Configure your {{es}} nodes to use the generated certificate for the transport layer](#encrypt-internode-communication). +You can add as many nodes as you want in a cluster but they must be able to communicate with each other. The communication between nodes in a cluster is handled by the transport module. To secure your cluster, you must ensure that internode communications are encrypted and verified, which is achieved with mutual TLS. -Refer to [Transport TLS/SSL settings](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#transport-tls-ssl-settings) for the complete list of available settings in {{es}}. +In a secured cluster, {{es}} nodes use certificates to identify themselves when communicating with other nodes. -## Considerations for using an external CA +The cluster must validate the authenticity of these certificates. The recommended approach is to trust a specific certificate authority (CA). When nodes are added to your cluster they must use a certificate signed by the same CA. -You might choose to use an external CA to generate transport certificates for node-to-node connections. +For the transport layer, we recommend using a separate, dedicated CA instead of an existing, possibly shared CA so that node membership is tightly controlled. -Transport connections between {{es}} nodes are security-critical and you must protect them carefully. Malicious actors who can observe or interfere with unencrypted node-to-node transport traffic can read or modify cluster data. A malicious actor who can establish a transport connection might be able to invoke system-internal APIs, including APIs that read or modify cluster data. +When you manually set up transport TLS, you can choose from the following CA options: -Carefully review [](/deploy-manage/security/self-tls-considerations.md) to ensure that the certificates that you provide meet the security requirements for transport connections. +* [Provide certificates from a private or third-party CA](#private-3p) +* [Use the `elasticsearch-certutil` tool to generate a CA unique to your cluster](#generate-certificates) -## Generate the certificate authority [generate-certificates] +### Provide certificates from a private or third-party CA [private-3p] -You can add as many nodes as you want in a cluster but they must be able to communicate with each other. The communication between nodes in a cluster is handled by the transport module. To secure your cluster, you must ensure that internode communications are encrypted and verified, which is achieved with mutual TLS. +You might choose to use a private or third-party CA to generate transport certificates for node-to-node connections. -In a secured cluster, {{es}} nodes use certificates to identify themselves when communicating with other nodes. +Transport connections between {{es}} nodes are security-critical and you must protect them carefully. Malicious actors who can observe or interfere with unencrypted node-to-node transport traffic can read or modify cluster data. A malicious actor who can establish a transport connection might be able to invoke system-internal APIs, including APIs that read or modify cluster data. -The cluster must validate the authenticity of these certificates. The recommended approach is to trust a specific certificate authority (CA). When nodes are added to your cluster they must use a certificate signed by the same CA. +Carefully review [](/deploy-manage/security/self-tls-considerations.md) to ensure that the certificates that you provide meet the security requirements for transport connections. + +After you obtain your certificate, place the certificate file in the `$ES_PATH_CONF` directory on **every** node in your cluster. -For the transport layer, we recommend using a separate, dedicated CA instead of an existing, possibly shared CA so that node membership is tightly controlled. Use the `elasticsearch-certutil` tool to generate a CA for your cluster. +### Generate the certificate authority using `elasticsearch-certutil` [generate-certificates] + +You can use the `elasticsearch-certutil` tool to generate a CA for your cluster. Using `elasticsearch-certutil` guarantees that your certificates meet {{es}} certificate requirements and security best practices. 1. Before starting {{es}}, use the `elasticsearch-certutil` tool on any single node to generate a CA for your cluster. @@ -67,7 +78,7 @@ For the transport layer, we recommend using a separate, dedicated CA instead of 1. Enter the password for your CA, or press **Enter** if you did not configure one in the previous step. 2. Create a password for the certificate and accept the default file name. - The output file is a keystore named `elastic-certificates.p12`. This file contains a node certificate, node key, and CA certificate. + The output file is a keystore named `elastSic-certificates.p12`. This file contains a node certificate, node key, and CA certificate. 3. On **every** node in your cluster, copy the `elastic-certificates.p12` file to the `$ES_PATH_CONF` directory. @@ -76,7 +87,9 @@ For the transport layer, we recommend using a separate, dedicated CA instead of The transport networking layer is used for internal communication between nodes in a cluster. When security features are enabled, you must use TLS to ensure that communication between the nodes is encrypted. -Now that you’ve generated a certificate authority and certificates, you’ll update your cluster to use these files. +Now that you’ve obtained your certificates, you’ll update your cluster to use these files. + +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 private or third-party CA. Refer to [Transport TLS/SSL settings](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#transport-tls-ssl-settings) 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. From fa7d7747f9cef0704d073d9df54005c8151e7439 Mon Sep 17 00:00:00 2001 From: shainaraskas <58563081+shainaraskas@users.noreply.github.com> Date: Thu, 13 Nov 2025 14:52:21 -0500 Subject: [PATCH 09/18] Update deploy-manage/security/set-up-basic-security.md --- 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 ac6c41595d..92a2c98a64 100644 --- a/deploy-manage/security/set-up-basic-security.md +++ b/deploy-manage/security/set-up-basic-security.md @@ -89,7 +89,7 @@ The transport networking layer is used for internal communication between nodes Now that you’ve obtained your certificates, you’ll update your cluster to use these files. -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 private or third-party CA. Refer to [Transport TLS/SSL settings](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#transport-tls-ssl-settings) full list of available settings. +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 a private or third-party CA. Refer to [Transport TLS/SSL settings](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#transport-tls-ssl-settings) 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. From b40ea3b24004423204cf9bf765933cf5b128ce47 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Thu, 13 Nov 2025 14:56:33 -0500 Subject: [PATCH 10/18] relocate note and reorder steps --- deploy-manage/security/different-ca.md | 3 +-- deploy-manage/security/k8s-transport-settings.md | 8 ++++---- 2 files changed, 5 insertions(+), 6 deletions(-) diff --git a/deploy-manage/security/different-ca.md b/deploy-manage/security/different-ca.md index 1a672313eb..622fea0424 100644 --- a/deploy-manage/security/different-ca.md +++ b/deploy-manage/security/different-ca.md @@ -12,8 +12,7 @@ products: # Different CA [update-node-certs-different] - -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. +If you have to trust a new CA from your organization, or you need to generate a new CA yourself, instruct your nodes to trust the new CA and then use this new CA to sign the new node certificates. :::{include} ./_snippets/own-ca-warning.md ::: diff --git a/deploy-manage/security/k8s-transport-settings.md b/deploy-manage/security/k8s-transport-settings.md index 6106c0a77e..64fae082f1 100644 --- a/deploy-manage/security/k8s-transport-settings.md +++ b/deploy-manage/security/k8s-transport-settings.md @@ -10,7 +10,10 @@ products: # Manage transport certificates on ECK [k8s-transport-settings] -The transport module in {{es}} is used for internal communication between nodes within the cluster as well as communication between remote clusters. Check the [{{es}} documentation](elasticsearch://reference/elasticsearch/configuration-reference/networking-settings.md) for details. For customization options of the HTTP layer, check [Access services](../deploy/cloud-on-k8s/accessing-services.md) and [HTTP TLS certificates](./k8s-https-settings.md). +The transport module in {{es}} is used for internal communication between nodes within the cluster as well as communication between remote clusters. Check the [{{es}} documentation](elasticsearch://reference/elasticsearch/configuration-reference/networking-settings.md) for details. For customization options of the HTTP layer, refer to [Access services](../deploy/cloud-on-k8s/accessing-services.md) and [HTTP TLS certificates](./k8s-https-settings.md). + +:::{include} ./_snippets/own-ca-warning.md +::: ## Customize the Transport Service [k8s_customize_the_transport_service] @@ -75,9 +78,6 @@ spec: ## Issue node transport certificates with third-party tools [k8s-transport-third-party-tools] -:::{include} ./_snippets/own-ca-warning.md -::: - When following the instructions in [Configure a custom Certificate Authority](#k8s-transport-ca) the issuance of certificates is orchestrated by the ECK operator and the operator needs access to the CAs private key. If this is undesirable it is also possible to configure node transport certificates without involving the ECK operator. The following two pre-requisites apply: 1. The tooling used must be able to issue individual certificates for each {{es}} node and dynamically add or remove certificates as the cluster scales up and down. From 462feef46d3188e6dca476502bd67b79337a3017 Mon Sep 17 00:00:00 2001 From: shainaraskas <58563081+shainaraskas@users.noreply.github.com> Date: Fri, 14 Nov 2025 10:15:37 -0500 Subject: [PATCH 11/18] Update deploy-manage/security/set-up-basic-security.md Co-authored-by: David Turner --- 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 92a2c98a64..9891827621 100644 --- a/deploy-manage/security/set-up-basic-security.md +++ b/deploy-manage/security/set-up-basic-security.md @@ -78,7 +78,7 @@ You can use the `elasticsearch-certutil` tool to generate a CA for your cluster. 1. Enter the password for your CA, or press **Enter** if you did not configure one in the previous step. 2. Create a password for the certificate and accept the default file name. - The output file is a keystore named `elastSic-certificates.p12`. This file contains a node certificate, node key, and CA certificate. + The output file is a keystore named `elastic-certificates.p12`. This file contains a node certificate, node key, and CA certificate. 3. On **every** node in your cluster, copy the `elastic-certificates.p12` file to the `$ES_PATH_CONF` directory. From 316536cb436369208562337c049b02fa9f10a558 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Fri, 14 Nov 2025 10:29:31 -0500 Subject: [PATCH 12/18] more edits --- .../security/self-tls-considerations.md | 4 ++- .../security/set-up-basic-security.md | 31 +++++++++---------- 2 files changed, 18 insertions(+), 17 deletions(-) diff --git a/deploy-manage/security/self-tls-considerations.md b/deploy-manage/security/self-tls-considerations.md index 896b4f2b42..98e975d65b 100644 --- a/deploy-manage/security/self-tls-considerations.md +++ b/deploy-manage/security/self-tls-considerations.md @@ -9,10 +9,12 @@ products: navigation_title: Private or 3P CA considerations --- -# Considerations for using an private or third-party CA for transport layer security +# Considerations for using a private or third-party CA for transport layer security By default, {{es}} uses mutual TLS (mTLS) to secure node-to-node transport connections. 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 node requires that certificates be issued by a trusted certificate authority, ensuring that only authorized nodes can connect. Configure trusted certificate authorities using settings in the [`xpack.security.transport.ssl.*`](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#transport-tls-ssl-settings) namespace, such as `xpack.security.transport.ssl.certificate_authorities` and `xpack.security.transport.ssl.truststore.path`. +{{es}} comes with a built-in tool called [`elasticsearch-certutil`](/deploy-manage/security/set-up-basic-security.md), which you can use to create and manage a dedicated certificate authority for each of your clusters, and to issue TLS certificates from this certificate authority. If you prefer not to use `elasticsearch-certutil`, then you must obtain the certificates from another certificate authority using standard TLS tools. This page explains the requirements and best practices to ensure that these certificates work correctly and protect your cluster properly. + ::::{warning} Transport connections between {{es}} nodes are security-critical and you must protect them carefully. Malicious actors who can observe or interfere with unencrypted node-to-node transport traffic can read or modify cluster data. A malicious actor who can establish a transport connection might be able to invoke system-internal APIs, including APIs that read or modify cluster data. :::: diff --git a/deploy-manage/security/set-up-basic-security.md b/deploy-manage/security/set-up-basic-security.md index 92a2c98a64..dba89cb659 100644 --- a/deploy-manage/security/set-up-basic-security.md +++ b/deploy-manage/security/set-up-basic-security.md @@ -40,18 +40,8 @@ For the transport layer, we recommend using a separate, dedicated CA instead of When you manually set up transport TLS, you can choose from the following CA options: +* [Use the `elasticsearch-certutil` tool to generate a CA unique to your cluster](#generate-certificates) (recommended) * [Provide certificates from a private or third-party CA](#private-3p) -* [Use the `elasticsearch-certutil` tool to generate a CA unique to your cluster](#generate-certificates) - -### Provide certificates from a private or third-party CA [private-3p] - -You might choose to use a private or third-party CA to generate transport certificates for node-to-node connections. - -Transport connections between {{es}} nodes are security-critical and you must protect them carefully. Malicious actors who can observe or interfere with unencrypted node-to-node transport traffic can read or modify cluster data. A malicious actor who can establish a transport connection might be able to invoke system-internal APIs, including APIs that read or modify cluster data. - -Carefully review [](/deploy-manage/security/self-tls-considerations.md) to ensure that the certificates that you provide meet the security requirements for transport connections. - -After you obtain your certificate, place the certificate file in the `$ES_PATH_CONF` directory on **every** node in your cluster. ### Generate the certificate authority using `elasticsearch-certutil` [generate-certificates] @@ -80,7 +70,14 @@ You can use the `elasticsearch-certutil` tool to generate a CA for your cluster. The output file is a keystore named `elastSic-certificates.p12`. This file contains a node certificate, node key, and CA certificate. -3. On **every** node in your cluster, copy the `elastic-certificates.p12` file to the `$ES_PATH_CONF` directory. + +### Provide certificates from a private or third-party CA [private-3p] + +You might choose to use a private or third-party CA to generate transport certificates for node-to-node connections. + +Transport connections between {{es}} nodes are security-critical and you must protect them carefully. Malicious actors who can observe or interfere with unencrypted node-to-node transport traffic can read or modify cluster data. A malicious actor who can establish a transport connection might be able to invoke system-internal APIs, including APIs that read or modify cluster data. + +Carefully review [](/deploy-manage/security/self-tls-considerations.md) to ensure that the certificates that you provide meet the security requirements for transport connections. ## Encrypt internode communications with TLS [encrypt-internode-communication] @@ -98,7 +95,9 @@ These steps assume that you [generated a CA and certificates](#generate-certific Complete the following steps **for each node in your cluster**. To join the same cluster, all nodes must share the same `cluster.name` value. -1. Open the `$ES_PATH_CONF/elasticsearch.yml` file and make the following changes: +1. Place the certificate or keystore file that you obtained in the `$ES_PATH_CONF` directory on **every** node in your cluster. If you generated a CA using `elasticsearch-certutil`, then this file is named `elastic-certificates.p12`. + +2. Open the `$ES_PATH_CONF/elasticsearch.yml` file and make the following changes: 1. Add the [`cluster-name`](elasticsearch://reference/elasticsearch/configuration-reference/miscellaneous-cluster-settings.md#cluster-name) setting and enter a name for your cluster: @@ -126,7 +125,7 @@ Complete the following steps **for each node in your cluster**. To join the same 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). -2. If you entered a password when creating the node certificate, run the following commands to store the password in the {{es}} keystore: +3. If you entered a password when creating the node certificate, run the following commands to store the password in the {{es}} keystore: ```shell ./bin/elasticsearch-keystore add xpack.security.transport.ssl.keystore.secure_password @@ -136,8 +135,8 @@ Complete the following steps **for each node in your cluster**. To join the same ./bin/elasticsearch-keystore add xpack.security.transport.ssl.truststore.secure_password ``` -3. Complete the previous steps for each node in your cluster. -4. On **every** node in your cluster, start {{es}}. The method for [starting](../maintenance/start-stop-services/start-stop-elasticsearch.md) and [stopping](../maintenance/start-stop-services/start-stop-elasticsearch.md) {{es}} varies depending on how you installed it. +4. Complete the previous steps for each node in your cluster. +5. On **every** node in your cluster, start {{es}}. The method for [starting](../maintenance/start-stop-services/start-stop-elasticsearch.md) and [stopping](../maintenance/start-stop-services/start-stop-elasticsearch.md) {{es}} varies depending on how you installed it. For example, if you installed {{es}} with an archive distribution (`tar.gz` or `.zip`), you can enter `Ctrl+C` on the command line to stop {{es}}. From 404c1db93b71986c8cb287ab958e1a0b947f1729 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Fri, 14 Nov 2025 13:46:51 -0500 Subject: [PATCH 13/18] use external instead of private/3p --- deploy-manage/security/_snippets/own-ca-warning.md | 2 +- deploy-manage/security/self-tls-considerations.md | 6 +++--- deploy-manage/security/set-up-basic-security.md | 8 ++++---- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/deploy-manage/security/_snippets/own-ca-warning.md b/deploy-manage/security/_snippets/own-ca-warning.md index 62211f9742..8def62f83c 100644 --- a/deploy-manage/security/_snippets/own-ca-warning.md +++ b/deploy-manage/security/_snippets/own-ca-warning.md @@ -1,5 +1,5 @@ :::{warning} Transport connections between {{es}} nodes are security-critical and you must protect them carefully. Malicious actors who can observe or interfere with node-to-node transport traffic can read or modify cluster data. A malicious actor who can establish a transport connection might be able to invoke system-internal APIs, including APIs that read or modify cluster data. -If you choose to issue node transport certificates using third-party tools, then carefully review [](/deploy-manage/security/self-tls-considerations.md) to ensure that the certificates that you provide meet the security requirements for transport connections. +If you choose to issue node transport certificates using an external CA, then carefully review [](/deploy-manage/security/self-tls-considerations.md) to ensure that the certificates that you provide meet the security requirements for transport connections. ::: \ No newline at end of file diff --git a/deploy-manage/security/self-tls-considerations.md b/deploy-manage/security/self-tls-considerations.md index 98e975d65b..cc21275ea6 100644 --- a/deploy-manage/security/self-tls-considerations.md +++ b/deploy-manage/security/self-tls-considerations.md @@ -6,10 +6,10 @@ applies_to: eck: products: - id: elasticsearch -navigation_title: Private or 3P CA considerations +navigation_title: External CA considerations --- -# Considerations for using a private or third-party CA for transport layer security +# Considerations for using an external CA for transport layer security By default, {{es}} uses mutual TLS (mTLS) to secure node-to-node transport connections. 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 node requires that certificates be issued by a trusted certificate authority, ensuring that only authorized nodes can connect. Configure trusted certificate authorities using settings in the [`xpack.security.transport.ssl.*`](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#transport-tls-ssl-settings) namespace, such as `xpack.security.transport.ssl.certificate_authorities` and `xpack.security.transport.ssl.truststore.path`. @@ -19,7 +19,7 @@ By default, {{es}} uses mutual TLS (mTLS) to secure node-to-node transport conne Transport connections between {{es}} nodes are security-critical and you must protect them carefully. Malicious actors who can observe or interfere with unencrypted node-to-node transport traffic can read or modify cluster data. A malicious actor who can establish a transport connection might be able to invoke system-internal APIs, including APIs that read or modify cluster data. :::: -## mTLS transport certificate requirements for private or third-party CAs +## mTLS transport certificate requirements for external CAs Obtain your transport certificates from a certificate authority that only issues certificates to {{es}} nodes permitted to connect to your cluster. Do not use a public certificate authority or an organization-wide private certificate authority, because these issue certificates to entities beyond your authorized cluster nodes. Use a dedicated private certificate authority for each {{es}} cluster. diff --git a/deploy-manage/security/set-up-basic-security.md b/deploy-manage/security/set-up-basic-security.md index f7e9035fe0..3208a427ed 100644 --- a/deploy-manage/security/set-up-basic-security.md +++ b/deploy-manage/security/set-up-basic-security.md @@ -41,7 +41,7 @@ For the transport layer, we recommend using a separate, dedicated CA instead of When you manually set up transport TLS, you can choose from the following CA options: * [Use the `elasticsearch-certutil` tool to generate a CA unique to your cluster](#generate-certificates) (recommended) -* [Provide certificates from a private or third-party CA](#private-3p) +* [Provide certificates from an external CA](#external-ca) ### Generate the certificate authority using `elasticsearch-certutil` [generate-certificates] @@ -71,9 +71,9 @@ You can use the `elasticsearch-certutil` tool to 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. -### Provide certificates from a private or third-party CA [private-3p] +### Provide certificates from an external CA [external-ca] -You might choose to use a private or third-party CA to generate transport certificates for node-to-node connections. +You might choose to use an external CA to generate transport certificates for node-to-node connections. An external CA is any CA that is not managed using `elasticsearch-certutil`. Transport connections between {{es}} nodes are security-critical and you must protect them carefully. Malicious actors who can observe or interfere with unencrypted node-to-node transport traffic can read or modify cluster data. A malicious actor who can establish a transport connection might be able to invoke system-internal APIs, including APIs that read or modify cluster data. @@ -86,7 +86,7 @@ The transport networking layer is used for internal communication between nodes Now that you’ve obtained your certificates, you’ll update your cluster to use these files. -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 a private or third-party CA. Refer to [Transport TLS/SSL settings](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#transport-tls-ssl-settings) full list of available settings. +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) 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. From b683d4ef36fb237a09b5f53b599edd41aa020e86 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Mon, 17 Nov 2025 13:17:56 -0500 Subject: [PATCH 14/18] additional feedback --- deploy-manage/security/_snippets/own-ca-warning.md | 2 +- ...tls-considerations.md => external-ca-transport.md} | 11 ++++++----- deploy-manage/security/set-up-basic-security.md | 2 +- deploy-manage/toc.yml | 2 +- 4 files changed, 9 insertions(+), 8 deletions(-) rename deploy-manage/security/{self-tls-considerations.md => external-ca-transport.md} (80%) diff --git a/deploy-manage/security/_snippets/own-ca-warning.md b/deploy-manage/security/_snippets/own-ca-warning.md index 8def62f83c..95e511f6d0 100644 --- a/deploy-manage/security/_snippets/own-ca-warning.md +++ b/deploy-manage/security/_snippets/own-ca-warning.md @@ -1,5 +1,5 @@ :::{warning} Transport connections between {{es}} nodes are security-critical and you must protect them carefully. Malicious actors who can observe or interfere with node-to-node transport traffic can read or modify cluster data. A malicious actor who can establish a transport connection might be able to invoke system-internal APIs, including APIs that read or modify cluster data. -If you choose to issue node transport certificates using an external CA, then carefully review [](/deploy-manage/security/self-tls-considerations.md) to ensure that the certificates that you provide meet the security requirements for transport connections. +If you choose to issue node transport certificates using an external CA, then carefully review [](/deploy-manage/security/external-ca-transport.md) to ensure that the certificates that you provide meet the security requirements for transport connections. ::: \ No newline at end of file diff --git a/deploy-manage/security/self-tls-considerations.md b/deploy-manage/security/external-ca-transport.md similarity index 80% rename from deploy-manage/security/self-tls-considerations.md rename to deploy-manage/security/external-ca-transport.md index cc21275ea6..41ee3ecdf1 100644 --- a/deploy-manage/security/self-tls-considerations.md +++ b/deploy-manage/security/external-ca-transport.md @@ -1,19 +1,20 @@ --- -navigation_title: Considerations applies_to: deployment: self: eck: products: - id: elasticsearch -navigation_title: External CA considerations +navigation_title: External CA for TLS --- -# Considerations for using an external CA for transport layer security +# Using an external certificate authority to secure node-to-node connections -By default, {{es}} uses mutual TLS (mTLS) to secure node-to-node transport connections. 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 node requires that certificates be issued by a trusted certificate authority, ensuring that only authorized nodes can connect. Configure trusted certificate authorities using settings in the [`xpack.security.transport.ssl.*`](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#transport-tls-ssl-settings) namespace, such as `xpack.security.transport.ssl.certificate_authorities` and `xpack.security.transport.ssl.truststore.path`. +By default, {{es}} uses mutual TLS (mTLS) to secure node-to-node transport connections. 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 node requires that certificates be issued by a trusted certificate authority (CA), ensuring that only authorized nodes can connect. Configure trusted certificate authorities using settings in the [`xpack.security.transport.ssl.*`](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#transport-tls-ssl-settings) namespace, such as `xpack.security.transport.ssl.certificate_authorities` and `xpack.security.transport.ssl.truststore.path`. -{{es}} comes with a built-in tool called [`elasticsearch-certutil`](/deploy-manage/security/set-up-basic-security.md), which you can use to create and manage a dedicated certificate authority for each of your clusters, and to issue TLS certificates from this certificate authority. If you prefer not to use `elasticsearch-certutil`, then you must obtain the certificates from another certificate authority using standard TLS tools. This page explains the requirements and best practices to ensure that these certificates work correctly and protect your cluster properly. +{{es}} comes with a built-in tool called [`elasticsearch-certutil`](/deploy-manage/security/set-up-basic-security.md), which you can use to create and manage a dedicated certificate authority for each of your clusters, and to issue TLS certificates from this certificate authority. If you prefer not to use `elasticsearch-certutil`, then you must obtain the certificates from another certificate authority using standard TLS tools. Any certificate authority that is not managed using `elasticsearch-certutil` is referred to as an "external certificate authority" or "external CA". + +This page explains the requirements and best practices to ensure that certificates generated using an external CA work correctly and protect your cluster properly. ::::{warning} Transport connections between {{es}} nodes are security-critical and you must protect them carefully. Malicious actors who can observe or interfere with unencrypted node-to-node transport traffic can read or modify cluster data. A malicious actor who can establish a transport connection might be able to invoke system-internal APIs, including APIs that read or modify cluster data. diff --git a/deploy-manage/security/set-up-basic-security.md b/deploy-manage/security/set-up-basic-security.md index 3208a427ed..8bcf4514b8 100644 --- a/deploy-manage/security/set-up-basic-security.md +++ b/deploy-manage/security/set-up-basic-security.md @@ -77,7 +77,7 @@ You might choose to use an external CA to generate transport certificates for no Transport connections between {{es}} nodes are security-critical and you must protect them carefully. Malicious actors who can observe or interfere with unencrypted node-to-node transport traffic can read or modify cluster data. A malicious actor who can establish a transport connection might be able to invoke system-internal APIs, including APIs that read or modify cluster data. -Carefully review [](/deploy-manage/security/self-tls-considerations.md) to ensure that the certificates that you provide meet the security requirements for transport connections. +Carefully review [](/deploy-manage/security/external-ca-transport.md) to ensure that the certificates that you provide meet the security requirements for transport connections. ## Encrypt internode communications with TLS [encrypt-internode-communication] diff --git a/deploy-manage/toc.yml b/deploy-manage/toc.yml index f34791f7bc..575db3b6f4 100644 --- a/deploy-manage/toc.yml +++ b/deploy-manage/toc.yml @@ -488,7 +488,7 @@ toc: children: - file: security/k8s-https-settings.md - file: security/k8s-transport-settings.md - - file: security/self-tls-considerations.md + - file: security/external-ca-transport.md - file: security/network-security.md children: - file: security/network-security-policies.md From 0566b5ea872948c49b5bba6cb486bbffa1b9b3ad Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Mon, 17 Nov 2025 14:28:50 -0500 Subject: [PATCH 15/18] wajiha feedback --- deploy-manage/security/_snippets/own-ca-warning.md | 2 +- deploy-manage/security/k8s-transport-settings.md | 2 +- deploy-manage/security/set-up-basic-security.md | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/deploy-manage/security/_snippets/own-ca-warning.md b/deploy-manage/security/_snippets/own-ca-warning.md index 95e511f6d0..e96ea36f23 100644 --- a/deploy-manage/security/_snippets/own-ca-warning.md +++ b/deploy-manage/security/_snippets/own-ca-warning.md @@ -1,5 +1,5 @@ :::{warning} Transport connections between {{es}} nodes are security-critical and you must protect them carefully. Malicious actors who can observe or interfere with node-to-node transport traffic can read or modify cluster data. A malicious actor who can establish a transport connection might be able to invoke system-internal APIs, including APIs that read or modify cluster data. -If you choose to issue node transport certificates using an external CA, then carefully review [](/deploy-manage/security/external-ca-transport.md) to ensure that the certificates that you provide meet the security requirements for transport connections. +If you choose to issue node transport certificates using an external CA, then carefully review [](/deploy-manage/security/external-ca-transport.md) to ensure that your certificates meet the security requirements for transport connections. ::: \ No newline at end of file diff --git a/deploy-manage/security/k8s-transport-settings.md b/deploy-manage/security/k8s-transport-settings.md index 64fae082f1..25d8a6d8ba 100644 --- a/deploy-manage/security/k8s-transport-settings.md +++ b/deploy-manage/security/k8s-transport-settings.md @@ -10,7 +10,7 @@ products: # Manage transport certificates on ECK [k8s-transport-settings] -The transport module in {{es}} is used for internal communication between nodes within the cluster as well as communication between remote clusters. Check the [{{es}} documentation](elasticsearch://reference/elasticsearch/configuration-reference/networking-settings.md) for details. For customization options of the HTTP layer, refer to [Access services](../deploy/cloud-on-k8s/accessing-services.md) and [HTTP TLS certificates](./k8s-https-settings.md). +The transport module in {{es}} is used for internal communication between nodes within the cluster as well as communication between remote clusters. For more information, refer to [Networking settings](elasticsearch://reference/elasticsearch/configuration-reference/networking-settings.md). For customization options of the HTTP layer, refer to [Access services](../deploy/cloud-on-k8s/accessing-services.md) and [HTTP TLS certificates](./k8s-https-settings.md). :::{include} ./_snippets/own-ca-warning.md ::: diff --git a/deploy-manage/security/set-up-basic-security.md b/deploy-manage/security/set-up-basic-security.md index 8bcf4514b8..c9d64d315a 100644 --- a/deploy-manage/security/set-up-basic-security.md +++ b/deploy-manage/security/set-up-basic-security.md @@ -19,7 +19,7 @@ This document focuses on the **manual configuration** of TLS for [{{es}} transpo In this guide, you will learn how to: -* [Either provide or generate security certificates](#obtain-certificates). +* [Generate or provide security certificates](#obtain-certificates). * [Configure your {{es}} nodes to use the generated certificate for the transport layer](#encrypt-internode-communication). Refer to [Transport TLS/SSL settings](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#transport-tls-ssl-settings) for the complete list of available settings in {{es}}. @@ -77,7 +77,7 @@ You might choose to use an external CA to generate transport certificates for no Transport connections between {{es}} nodes are security-critical and you must protect them carefully. Malicious actors who can observe or interfere with unencrypted node-to-node transport traffic can read or modify cluster data. A malicious actor who can establish a transport connection might be able to invoke system-internal APIs, including APIs that read or modify cluster data. -Carefully review [](/deploy-manage/security/external-ca-transport.md) to ensure that the certificates that you provide meet the security requirements for transport connections. +Carefully review [](/deploy-manage/security/external-ca-transport.md) to ensure that your certificates meet the security requirements for transport connections. ## Encrypt internode communications with TLS [encrypt-internode-communication] From 2468cc74a41781efba20a0cceb8de41f0768e8f9 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Mon, 17 Nov 2025 14:42:20 -0500 Subject: [PATCH 16/18] wajiha feedback --- .../security/secure-cluster-communications.md | 2 ++ .../security/set-up-basic-security.md | 28 +++++++++---------- 2 files changed, 16 insertions(+), 14 deletions(-) diff --git a/deploy-manage/security/secure-cluster-communications.md b/deploy-manage/security/secure-cluster-communications.md index d1eb532ff4..421108c1ac 100644 --- a/deploy-manage/security/secure-cluster-communications.md +++ b/deploy-manage/security/secure-cluster-communications.md @@ -4,10 +4,12 @@ mapped_pages: - https://www.elastic.co/guide/en/elasticsearch/reference/current/security-basic-setup.html - https://www.elastic.co/guide/en/kibana/current/elasticsearch-mutual-tls.html applies_to: + serverless: deployment: self: eck: ece: + ess: products: - id: elasticsearch - id: kibana diff --git a/deploy-manage/security/set-up-basic-security.md b/deploy-manage/security/set-up-basic-security.md index c9d64d315a..8ee7470042 100644 --- a/deploy-manage/security/set-up-basic-security.md +++ b/deploy-manage/security/set-up-basic-security.md @@ -47,28 +47,28 @@ When you manually set up transport TLS, you can choose from the following CA opt You can use the `elasticsearch-certutil` tool to generate a CA for your cluster. Using `elasticsearch-certutil` guarantees that your certificates meet {{es}} certificate requirements and security best practices. -1. Before starting {{es}}, use the `elasticsearch-certutil` tool on any single node to generate a CA for your cluster. +1. Before starting {{es}}, generate the CA: + 1. Use the `elasticsearch-certutil` tool on any single node to generate a CA for your cluster. ```shell ./bin/elasticsearch-certutil ca ``` - 1. When prompted, accept the default file name, which is `elastic-stack-ca.p12`. This file contains the public certificate for your CA and the private key used to sign certificates for each node. - 2. Enter a password for your CA. You can choose to leave the password blank if you’re not deploying to a production environment. + 2. When prompted, accept the default file name, which is `elastic-stack-ca.p12`. This file contains the public certificate for your CA and the private key used to sign certificates for each node. + 3. Enter a password for your CA. You can choose to leave the password blank if you’re not deploying to a production environment. -2. On any single node, generate a certificate and private key for the nodes in your cluster. You include the `elastic-stack-ca.p12` output file that you generated in the previous step. +2. Generate the certificate: + 1. On any single node, generate a certificate and private key for the nodes in your cluster. Include the `elastic-stack-ca.p12` output file that you generated in the previous step. - ```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`. + ```shell + ./bin/elasticsearch-certutil cert --ca elastic-stack-ca.p12 <1> + ``` + 1. The `--ca` flag must contain the name of the CA file used to sign your certificates. The default file name from the `elasticsearch-certutil` tool is `elastic-stack-ca.p12`. - 1. Enter the password for your CA, or press **Enter** if you did not configure one in the previous step. - 2. Create a password for the certificate and accept the default file name. + 2. Enter the password for your CA, or press **Enter** if you did not configure one in the previous step. + 3. Create a password for the certificate and accept the default file name. - The output file is a keystore named `elastic-certificates.p12`. This file contains a node certificate, node key, and CA certificate. + The output file is a keystore named `elastic-certificates.p12`. This file contains a node certificate, node key, and CA certificate. ### Provide certificates from an external CA [external-ca] @@ -86,7 +86,7 @@ The transport networking layer is used for internal communication between nodes Now that you’ve obtained your certificates, you’ll update your cluster to use these files. -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) full list of available settings. +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. From 555c0f3d16004c7fe2eb3e44c2136ee1ac66495d Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Mon, 17 Nov 2025 14:48:03 -0500 Subject: [PATCH 17/18] wajiha feedback ++ --- deploy-manage/security/_snippets/eck-transport.md | 2 +- deploy-manage/security/k8s-transport-settings.md | 2 +- deploy-manage/security/secure-cluster-communications.md | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/deploy-manage/security/_snippets/eck-transport.md b/deploy-manage/security/_snippets/eck-transport.md index c357f30ce9..c7769709c4 100644 --- a/deploy-manage/security/_snippets/eck-transport.md +++ b/deploy-manage/security/_snippets/eck-transport.md @@ -1 +1 @@ -{{es}} transport security and TLS certificates are automatically configured by the operator, but you can still [customize its service and CA certificates](/deploy-manage/security/k8s-transport-settings.md). +{{es}} transport security and TLS certificates are automatically configured by the operator, but you can still [customize the {{es}} transport service, certificate authority, and certificates](/deploy-manage/security/k8s-transport-settings.md). diff --git a/deploy-manage/security/k8s-transport-settings.md b/deploy-manage/security/k8s-transport-settings.md index 25d8a6d8ba..3d9cc405d1 100644 --- a/deploy-manage/security/k8s-transport-settings.md +++ b/deploy-manage/security/k8s-transport-settings.md @@ -39,7 +39,7 @@ When you change the `clusterIP` setting of the service, ECK deletes and re-creat ## Configure a custom Certificate Authority [k8s-transport-ca] -{{es}} uses X.509 certificates to establish encrypted and authenticated connections across nodes in the cluster. By default, ECK creates a self-signed CA certificate to issue a certificate [for each node in the cluster](/deploy-manage/security/set-up-basic-security.md#encrypt-internode-communication). +{{es}} uses X.509 certificates to establish encrypted and authenticated connections across nodes in the cluster. By default, ECK creates a CA to issue a self-signed certificate [for each node in the cluster](/deploy-manage/security/set-up-basic-security.md#encrypt-internode-communication). You can use a Kubernetes secret to provide your own CA instead of the self-signed certificate that ECK will then use to create node certificates for transport connections. The CA certificate must be stored in the secret under `ca.crt` and the private key must be stored under `ca.key`. diff --git a/deploy-manage/security/secure-cluster-communications.md b/deploy-manage/security/secure-cluster-communications.md index 421108c1ac..2671732d3e 100644 --- a/deploy-manage/security/secure-cluster-communications.md +++ b/deploy-manage/security/secure-cluster-communications.md @@ -67,9 +67,9 @@ The way that transport layer security is managed depends on your deployment type {{es}} transport security is fully managed by Elastic, and no configuration is required. :::: -::::{admonition}{tab-item} ECE +::::{tab-item} ECE :sync: ece -{{es}} transport security is fully managed by {{ece}} platform, and no configuration is required. +{{es}} transport security is fully managed by the {{ece}} platform, and no configuration is required. :::: ::::{tab-item} ECK From 580e6325d332df1c09ba8fd4172d59d98b429448 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Mon, 17 Nov 2025 14:51:55 -0500 Subject: [PATCH 18/18] define ca --- deploy-manage/security/same-ca.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/deploy-manage/security/same-ca.md b/deploy-manage/security/same-ca.md index 522b485bbc..f7c59969bd 100644 --- a/deploy-manage/security/same-ca.md +++ b/deploy-manage/security/same-ca.md @@ -14,9 +14,9 @@ products: # Same CA [update-node-certs-same] -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 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. +This procedure assumes that the you have access to the certificate and key that was originally generated (or otherwise held by your organization) and used 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 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 and use the same filenames, {{es}} reloads the files starts using the new certificates and keys. +If you have access to the certificate authority (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 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 [a recommended practice](updating-certificates.md#use-rolling-restarts) when updating certificates. Therefore, the following steps include a node restart after updating each certificate.