Move own CA transport layer mtls guidance to security docs (#3932)

Author: shainaraskas

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

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

deploy-manage/security/different-ca.md

@@ -12,8 +12,11 @@ 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, 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
+:::
 
-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.
 
 ## Generate a new certificate for the transport layer [node-certs-different-transport]
 

deploy-manage/security/external-ca-transport.md

@@ -0,0 +1,42 @@
+---
+applies_to:
+  deployment:
+    self:
+    eck:
+products:
+  - id: elasticsearch
+navigation_title: External CA for TLS
+---
+
+# 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 (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. 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.
+::::
+
+## Transport mTLS 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.
+
+Certificates used for transport 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. 
+
+### Transport certificates vs. HTTP certificates
+
+Transport certificates have different security requirements than [HTTP certificates](/deploy-manage/security/secure-cluster-communications.md#encrypt-http-communication). HTTP server certificates don't require the `clientAuth` Extended Key Usage extension because they are used solely for server authentication, regardless of whether mTLS is enabled. In practice, HTTP connections don't typically use mTLS because HTTP has its own authentication mechanisms. 
+
+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]
+
+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 might 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/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. 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
+:::
 
 ## Customize the Transport Service [k8s_customize_the_transport_service]
 

deploy-manage/security/same-ca.md

@@ -16,12 +16,15 @@ products:
 
 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.
 
-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.
 
 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

@@ -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
@@ -57,36 +59,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
+::::{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
+::::{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.