Move own CA transport layer mtls guidance to security docs #3932
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1 +1 @@ | ||
| {{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). |
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -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. | ||||||
|
Contributor
There was a problem hiding this comment. Is sentence 3 an explanation of sentence 2, or is it a separate thing? If it's an explanation, you could clarify that by saying something like:
Suggested change
Collaborator
Author
There was a problem hiding this comment. @DaveCTurner can you answer this? not sure if these two statements technically mean two different things
Contributor
There was a problem hiding this comment. They're separate things. Establishing a connection is different from interfering with traffic on existing 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. | ||||||
| ::: | ||||||
|
Contributor
There was a problem hiding this comment. I don't understand the concept of an
Contributor
There was a problem hiding this comment. This is defined in these very docs:
|
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,40 @@ | ||||||
| --- | ||||||
| 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. | ||||||
|
|
||||||
shainaraskas marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| ::::{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. | ||||||
| :::: | ||||||
|
|
||||||
| ## 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. | ||||||
|
Contributor
There was a problem hiding this comment. This first sentence should probably be considered or used for comparison in the section "Transport vs HTTP". We probably want to explain that this is not that relevant for HTTP, and for HTTP, for operational purposes (and because we have extra authentication and authorization mechanisms), it's common to not use dedicated CAs per cluster, and even public / organizational CAs that are automatically trusted by the clients. Of course this will depend on the use case, as in certain use cases it might have sense to have the HTTP layer also super-protected at TLS level. We should end up with the recommendation that as minimum, if they use private CAs, they should create a private CA to generate transport certs, and another private CA to generate HTTP certs. This relates with the comment in the "transport vs HTTP" section.
Contributor
There was a problem hiding this comment. I'm not sure what concrete change you're suggesting here. The title of this page is |
||||||
|
|
||||||
| 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. | ||||||
|
Contributor
There was a problem hiding this comment.
Suggested change
A public certificate without clientAuth is perfectly valid for mTLS in general, but not for ES transport mTLS.
Contributor
There was a problem hiding this comment. I disagree, it depends whether you read "mTLS" as "everything about setting up a mutually-authenticated TLS connection" or "client-certificate authentication". The general practice seems to be the latter, and that's how we're using it here. |
||||||
|
|
||||||
| ### 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 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. | ||||||
|
Contributor
There was a problem hiding this comment. We need to rephrase this somehow, because server certs without The transport specific thing is that when it comes to transport layer Elasticsearch node is a client and a server at the same time, and that's why the But in general for mTLS on HTTP (where clients and servers are different entities), the clients and servers use different certificates, and a server cert without
First clause is perfectly ok and true, but it's not related with the second, which is also correct per-se.
Contributor
There was a problem hiding this comment.
Not only the certificates, I think we also want users to use different CAs for HTTP and transport, so:
thoughts? I think this section (which is super important IMO) needs a few paragraphs, bullets and pointers.
Contributor
There was a problem hiding this comment. As above I would rather not split hairs about whether mTLS refers just to the client-certificate authentication or the whole connection process. Likewise, you're right that there are many other concerns (mostly addressed elsewhere in this text) about how to obtain these certificates. Yet, a very common mistake is for users to use the same certificate for both uses, and it is vitally important to have a sentence calling out this case. |
||||||
|
|
||||||
| ## 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 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. | ||||||
| :::: | ||||||
Uh oh!
There was an error while loading. Please reload this page.