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.
|
@shainaraskas , would you review when you get a moment? Thanks! |
|
@elastic/admin-docs , would you review when you get a moment? Thanks! |
There was a problem hiding this comment.
thanks for this addition!
this PR injects a lot of info that is secondary to the topic at hand on these specific pages. I've suggested paring things down, and perhaps adding some more detail to the relevant settings in the setting reference as a backup. let me know what you think.
| When the same file is configured as both the keystore and truststore, or when only `keystore.path` is set and {{es}} uses that file as the truststore, peer node certificates in the file are trusted directly. The same behavior applies if a peer's leaf certificate is listed in `xpack.security.transport.ssl.certificate_authorities`. In these configurations, {{es}} does not reject connections from nodes presenting an expired certificate that is directly trusted, regardless of the `verification_mode` setting. Internode communication remains encrypted, and the cluster can continue to operate normally, including restarts and adding new nodes that use the same certificate material. | ||
| :::: | ||
|
|
||
| 1. If you want to use hostname verification, set the verification mode to `full`. You should generate a different certificate for each host that matches the DNS or IP address. See the `xpack.security.transport.ssl.verification_mode` parameter in [TLS settings](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#transport-tls-ssl-settings). |
There was a problem hiding this comment.
because this is a procedure, we should keep it to the context of this config, and include these other details only where they're relevant
| 1. If you want to use hostname verification, set the verification mode to `full`. You should generate a different certificate for each host that matches the DNS or IP address. See the `xpack.security.transport.ssl.verification_mode` parameter in [TLS settings](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#transport-tls-ssl-settings). | |
| 1. If you want to use hostname verification, set the verification mode to `full`. You should generate a different certificate for each host that matches the DNS or IP address. See the `xpack.security.transport.ssl.verification_mode` parameter in [TLS settings](elasticsearch://reference/elasticsearch/configuration-reference/security-settings.md#transport-tls-ssl-settings). | |
| ::::{note} | |
| When the same file is configured as both the keystore and truststore, peer node certificates in the file are trusted directly. {{es}} does not reject connections from nodes presenting an expired certificate that is directly trusted, regardless of the `verification_mode` setting. Internode communication remains encrypted, and the cluster can continue to operate normally, including restarts and adding new nodes that use the same certificate material. | |
| :::: |
or when only
keystore.pathis set and {{es}} uses that file as the truststore, peer node certificates in the file are trusted directly. The same behavior applies if a peer's leaf certificate is listed inxpack.security.transport.ssl.certificate_authorities.
this info likely needs to go on the relevant settings in https://www.elastic.co/docs/reference/elasticsearch/configuration-reference/security-settings#transport-tls-ssl-settings
... the core message of this note should probably also go in the reference on the relevant settings
There was a problem hiding this comment.
Are you referring to the trust store path setting xpack.security.transport.ssl.truststore.path in the "Transport TLS/SSL key and trusted certificate settings" section?
The setting descriptions are all quite short on the page, so emphasizing the impact of sharing keystore/truststore might be imbalanced.
There was a problem hiding this comment.
They are short, but if we have context that will help people use the settings better and there is no more ideal place, there is nothing wrong with adding more detail. some of our settings in the reference have a couple of paragraphs. I expect this will only end up adding maybe two sentences to each spot because we only need the details specific to that setting.
Co-authored-by: shainaraskas <58563081+shainaraskas@users.noreply.github.com>
Co-authored-by: shainaraskas <58563081+shainaraskas@users.noreply.github.com>
Co-authored-by: shainaraskas <58563081+shainaraskas@users.noreply.github.com>
Co-authored-by: shainaraskas <58563081+shainaraskas@users.noreply.github.com>
shainaraskas
left a comment
shainaraskas
left a comment
There was a problem hiding this comment.
looks great, thanks (and thanks for your patience!)
3 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.