add new considerations page, warnings to relevant procedures

Author: shainaraskas

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.
+:::

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!).

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.

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
 

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.

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.
 ::::

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.

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