Document transport TLS certificate expiry behavior - #7918
Conversation
Manual transport TLS setup recommends using the same PKCS#12 file for both keystore and truststore without explaining that expired peer certificates may still be accepted. This gap confused users and was raised in elastic/security#1966. Clarify that elastic-certificates.p12 acts as a cluster- membership key and note the expiry implications when the same file is used for keystore and truststore. Add a brief auto- configuration note in security-files.md covering transport.p12, enrollment tokens, and a cross-link to the manual setup guide.
Elastic Docs AI PR menuCheck the box to run an AI review for this pull request.
Powered by GitHub Agentic Workflows and docs-actions. For more information, reach out to the docs team. |
🔍 Preview links for changed docs |
✅ Elastic Docs Style Checker (Vale)No issues found on modified lines! The Vale linter checks documentation changes against the Elastic Docs style guide. To use Vale locally or report issues, refer to Elastic style guide for Vale. |
jfreden
left a comment
jfreden
left a comment
There was a problem hiding this comment.
Thanks for adding this. I think just a docs change for closing the security issue is the right approach. I left a couple of suggestions and also have some high level ideas:
- Would it make sense to add add some information to
auto-security-configabout what is actually written? Something like:
Autoconfig sets
transport.p12as both keystore and truststore with verification_mode: certificate, the file functions as a cluster-membership key. Transport CA and node certs are valid for 99 years while the HTTP CA is 3 years and the HTTP certificate 2 years.
- Might be out of scope for this PR, but should
add-and-remove-elasticsearch-nodes.mdand_snippets/enroll-nodes.mdbe updated with some more information about what happens actually happens to security material during enrollement?
| ``` | ||
|
|
||
| ::::{note} | ||
| When the same PKCS#12 file is configured as both the keystore and truststore, peer node certificates in that file are trusted directly. In this configuration, {{es}} does not reject connections from nodes presenting an expired certificate from the same file, even when `verification_mode` is set to `certificate`. Internode communication remains encrypted, and the cluster can continue to operate normally, including restarts and adding new nodes that use the same file. |
There was a problem hiding this comment.
When the same PKCS#12 file is configured as both the keystore and truststore, peer node certificates in that file are trusted directly.
There is an implicit fallback here where only configuring the keystore will result in the keystore turning into the truststore, so a user that tries to "fix" the issue by removing the truststore config would end up in the same situation.
The note also reads as PKCS#12 specific, the same thing would happen with PEM certs certificate_authorities: [node.crt, ca.crt] (or any CA list containing a leaf that peers present).
even when
verification_modeis set tocertificate
This isn't really relevant, since the same thing would happen with any verification mode I think?
Should this also mention that even a CA-only truststore doesn't check the CA's own expiry? I guess that's kind of implied.
There was a problem hiding this comment.
Good callouts. Updated in commit 8ac384c
| ``` No newline at end of file | ||
| ``` | ||
|
|
||
| Security auto-configuration sets `certs/transport.p12` as both the transport keystore and truststore on each node. Auto-generated transport certificates have a long validity period and are unlikely to expire under normal operation. To add nodes, use an [enrollment token](/deploy-manage/maintenance/add-and-remove-elasticsearch-nodes.md#_enroll_nodes_in_an_existing_cluster_5) rather than copying `transport.p12` between nodes. For manual transport TLS setup and certificate expiry behavior when the same PKCS#12 file is shared across all nodes, refer to [Set up transport TLS](/deploy-manage/security/set-up-basic-security.md). No newline at end of file |
There was a problem hiding this comment.
Instead of "Long validity period" we can say 99 years and maybe mention that http certs have a 3 year validity period. WDYT?
There was a problem hiding this comment.
That's where I started as well, since those are helpful figures. But I decided against that since (1) it could invite scrutiny and (2) it could also get stale.
I'm open to either.
There was a problem hiding this comment.
Yes, I was on the fence too when suggesting. Let's keep it as is.
2 participants
Manual transport TLS setup recommends using the same PKCS#12 file for both keystore and truststore without explaining that expired peer certificates may still be accepted. This gap confused users and was raised in elastic/security#1966.
Clarify that elastic-certificates.p12 acts as a cluster- membership key and note the expiry implications when the same file is used for keystore and truststore. Add a brief auto- configuration note in security-files.md covering transport.p12, enrollment tokens, and a cross-link to the manual setup guide.