Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 25 commits into
base: main
Choose a base branch
from
Open

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

Changes from 1 commit
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
4ef3fbb
dave-content
shainaraskas Nov 13, 2025
3f5b433
add new considerations page, warnings to relevant procedures
shainaraskas Nov 13, 2025
c401bfa
too many brackets
shainaraskas Nov 13, 2025
c60da3e
Merge branch 'main' into self-tls-considerations
shainaraskas Nov 13, 2025
b94310e
polish
shainaraskas Nov 13, 2025
e43a868
Merge branch 'self-tls-considerations' of github.com:elastic/docs-con…
shainaraskas Nov 13, 2025
60e11e0
polish 2
shainaraskas Nov 13, 2025
74894f3
Update deploy-manage/security/self-tls-considerations.md
shainaraskas Nov 13, 2025
141c98d
dave feedback
shainaraskas Nov 13, 2025
59aaf4d
Merge branch 'self-tls-considerations' of github.com:elastic/docs-con…
shainaraskas Nov 13, 2025
d6ecddf
basic security tutorial now mostly works for private/3P CA case
shainaraskas Nov 13, 2025
fa7d774
Update deploy-manage/security/set-up-basic-security.md
shainaraskas Nov 13, 2025
b40ea3b
relocate note and reorder steps
shainaraskas Nov 13, 2025
d2ff6e6
Merge branch 'self-tls-considerations' of github.com:elastic/docs-con…
shainaraskas Nov 13, 2025
462feef
Update deploy-manage/security/set-up-basic-security.md
shainaraskas Nov 14, 2025
316536c
more edits
shainaraskas Nov 14, 2025
89ec319
Merge branch 'self-tls-considerations' of github.com:elastic/docs-con…
shainaraskas Nov 14, 2025
404c1db
use external instead of private/3p
shainaraskas Nov 14, 2025
b683d4e
additional feedback
shainaraskas Nov 17, 2025
0566b5e
wajiha feedback
shainaraskas Nov 17, 2025
2468cc7
wajiha feedback
shainaraskas Nov 17, 2025
555c0f3
wajiha feedback ++
shainaraskas Nov 17, 2025
580e632
define ca
shainaraskas Nov 17, 2025
9cd7ad3
restore stuff removed in bad edit
shainaraskas Nov 18, 2025
df3fe49
edu david feedback
shainaraskas Nov 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions deploy-manage/security/external-ca-transport.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,15 +20,17 @@ This page explains the requirements and best practices to ensure that certificat
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
## 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.
Copy link
Contributor

@eedugon eedugon Nov 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

@DaveCTurner DaveCTurner Nov 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure what concrete change you're suggesting here. The title of this page is Using an external certificate authority to secure node-to-node connections so the context is already set that this is about transport connections, not HTTP. Then we follow up with a section about how this stuff all differs from HTTP that I think covers your points here.

Copy link
Contributor

@eedugon eedugon Nov 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 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 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.
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 CA or certificate for both HTTP and transport connections.
Copy link
Collaborator Author

@shainaraskas shainaraskas Nov 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

note "CA or certificate" here

Copy link
Contributor

@eedugon eedugon Nov 19, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like it a lot, thanks!!


## Turning off mTLS for transport connections [turn-off-mtls]

Expand Down
Loading