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 |
|---|---|---|
| @@ -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. | ||
shainaraskas marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| 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. | ||
shainaraskas marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
| ::: | ||
shainaraskas marked this conversation as resolved.
Show resolved
Hide resolved
|
| 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
Contributor
There was a problem hiding this comment. Sorry if I wasn't clear enough @DaveCTurner , I wasn't suggesting a change there, just highlighting that the style and content of that first paragraph could be used in the section where we compare HTTP and transport. |
||||||
|
|
||||||
| 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. | ||||||
|
||||||
| 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. | |
| Certificates used for transport mTLS must either have no Extended Key Usage extension, or include both `clientAuth` and `serverAuth` values in the extension, because the same certificate is used by the node when acting as client and server. Public certificate authorities typically omit the `clientAuth` value in the Extended Key Usage extension, making them unsuitable for {{es}} transport mTLS. |
A public certificate without clientAuth is perfectly valid for mTLS in general, but not for ES transport mTLS.
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.
There was a problem hiding this comment.
I think this clarification is helpful just because these are transport mtls requirements specifically (and our requirements for http certs are different)
There was a problem hiding this comment.
"client-certificate authentication"... and that's how we're using it here.
with client-certificate authentication, in the majority of (common) cases of client-server communications, the client uses a certificate and the server uses a different certificate, hence, typically, the server certificate does not require clientAuth extension, as it's only for server-acting purposes.
The case of Elasticsearch transport is special, because Elasticsearch acts as a client and a server at the same time, using its certificate, hence the cert needs both values.
That's why I didn't want to write a generic sentence causing the impression that in general certificates for mTLS require both extensions, as that could potentially cause a reader to think, that, for example, for an hypothetical use case of mTLS for HTTP, they need a server cert with both values, which would be an incorrect assumption.
But I could be completely wrong, sorry in such case.
It's true that for server-to-server communications and mTLS, the standard would be your point of view @DaveCTurner, I didn't have that in mind earlier.
Outdated
There was a problem hiding this comment.
We need to rephrase this somehow, because server certs without clientAuth extension are perfectly valid for mTLS on HTTP servers.
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 clientAuth + serverAuth is needed in the transport cert.
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 clientAuth would actually be expected. This relation feels incorrect:
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
clientAuthvalue in their Extended Key Usage extension.
First clause is perfectly ok and true, but it's not related with the second, which is also correct per-se.
We should clarify first my suggestion in the ES PR before updating this. In the meantime this is the suggested sentence (which should be improved):
The security requirements for transport certificates (as defined by the
xpack.security.transport.ssl.*settings) are significantly different from the security requirements for HTTP certificates (as defined by thexpack.security.http.ssl.*settings). For HTTP server certificates, it often makes sense to obtain the nodes' HTTP certificates from a public certificate authority, or from an organization-wide private certificate authority. HTTP server certificates don't require theclientAuthExtended Key Usage extension because they are used solely for server authentication, regardless of whether mTLS is enabled. In practice, HTTP connections do not generally use mTLS, since HTTP has its own authentication mechanisms. It is almost always a mistake to use the same certificate for both HTTP and transport connections.
There was a problem hiding this comment.
In most cases, you should not use the same certificate for both HTTP and transport connections.
Not only the certificates, I think we also want users to use different CAs for HTTP and transport, so:
- Dedicated (purely private) CA for transport, creating certs for nodes transport layer.
- Whatever the user prefers based on their security requirements for HTTP, even a purely private CA too, but a different one that the transport CA.
thoughts?
I think this section (which is super important IMO) needs a few paragraphs, bullets and pointers.
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.
There was a problem hiding this comment.
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.
yes, totally agree!
I realize now that all the misunderstanding and what I was considering "not accurate" in the writing it's because I have in my mind a standard client to server communication model, and I believe you are thinking of a server - server communication flow.
With that a server-to-server communication model in mind (typical in clusters and used in Elasticsearch transport), then the statement about mTLS requiring both clientAuth and serverAuth extension in the server certificate becomes accurate and valid. Sorry I wasn't finding it accurate because I was thinking in a client-to-server basic flow.
Anyway I think latest changes by @shainaraskas already improve this.
Uh oh!
There was an error while loading. Please reload this page.