Skip to content

Document transport TLS certificate expiry behavior #7918

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
ebarlas wants to merge 5 commits into
base: main
Choose a base branch
from
+8 −2
Open

Document transport TLS certificate expiry behavior #7918

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
2bb2768
Document transport TLS certificate expiry behavior
ebarlas Aug 12, 2026
ff75afa
Revert transport.p12 to reduce change scope
ebarlas Aug 13, 2026
7f25469
Remove sentence in certificate expiry note
ebarlas Aug 13, 2026
9bea469
Remove another sentence
ebarlas Aug 13, 2026
8ac384c
Improve the description
ebarlas Aug 13, 2026
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
4 changes: 3 additions & 1 deletion deploy-manage/deploy/self-managed/_snippets/security-files.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,4 +21,6 @@ Use the following command to retrieve the password for `transport.p12`:

```sh
bin/elasticsearch-keystore show xpack.security.transport.ssl.keystore.secure_password
```
```

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).

@jfreden jfreden Aug 13, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Instead of "Long validity period" we can say 99 years and maybe mention that http certs have a 3 year validity period. WDYT?

@ebarlas ebarlas Aug 13, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

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.

@jfreden jfreden Aug 14, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Yes, I was on the fence too when suggesting. Let's keep it as is.

6 changes: 5 additions & 1 deletion deploy-manage/security/set-up-basic-security.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -113,7 +113,7 @@ Complete the following steps **for each node in your cluster**. To join the same

3. Add the following settings to enable internode communication and provide access to the node’s certificate.

Because you are using the same `elastic-certificates.p12` file on every node in your cluster, set the verification mode to `certificate`:
Use the same `elastic-certificates.p12` file on every node in your cluster. This file acts as a cluster-membership key: any node with a copy of the file can join the cluster and will trust other nodes using the same file. Because every node presents the same certificate, set the verification mode to `certificate`:

```yaml
xpack.security.transport.ssl.enabled: true
Expand All @@ -123,6 +123,10 @@ Complete the following steps **for each node in your cluster**. To join the same
xpack.security.transport.ssl.truststore.path: elastic-certificates.p12
```

::::{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.

@jfreden jfreden Aug 13, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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_mode is set to certificate

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.

@ebarlas ebarlas Aug 13, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Good callouts. Updated in commit 8ac384c

::::

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).

3. If you entered a password when creating the node certificate, run the following commands to store the password in the {{es}} keystore:
Expand Down
Loading