Skip to content

Commit 8a4b3d7

Browse files
[DOCS] Clarify not all PKCS12 usable as truststores (#30750)
Although elasticsearch-certutil generates PKCS#12 files which are usable as both keystore and truststore this is uncommon in practice. Settle these expectations for the users following our security guides.
1 parent 028081b commit 8a4b3d7

File tree

3 files changed

+21
-4
lines changed

3 files changed

+21
-4
lines changed

x-pack/docs/en/security/securing-communications/node-certificates.asciidoc

+1-1
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
TLS requires X.509 certificates to perform encryption and authentication of the
66
application that is being communicated with. In order for the communication
77
between nodes to be truly secure, the certificates must be validated. The
8-
recommended approach for validating certificate authenticity in a {es} cluster
8+
recommended approach for validating certificate authenticity in an {es} cluster
99
is to trust the certificate authority (CA) that signed the certificate. By doing
1010
this, as nodes are added to your cluster they just need to use a certificate
1111
signed by the same CA and the node is automatically allowed to join the cluster.

x-pack/docs/en/security/securing-communications/tls-transport.asciidoc

+7-3
Original file line numberDiff line numberDiff line change
@@ -30,9 +30,13 @@ See <<ssl-tls-settings, `xpack.ssl.verification_mode`>> for a description of the
3030
<2> If you created a separate certificate for each node, then you might need to
3131
customize this path on each node. If the filename matches the node name, you can
3232
use the `certs/${node.name}.p12` format, for example.
33-
<3> The `elasticsearch-certutil` output includes the CA certificate inside the
34-
PKCS#12 keystore, therefore the keystore can also be used as the truststore.
35-
This name should match the `keystore.path` value.
33+
<3> The `elasticsearch-certutil` outputs a PKCS#12 keystore which includes the
34+
CA certificate as a trusted certificate entry. This allows for the keystore to
35+
also be used as a truststore. In this case, the path value should match
36+
the `keystore.path` value.
37+
Note, however, that this is not the general rule. There are keystores that cannot be
38+
used as trustores, only
39+
{ref}/security-settings.html#pkcs12-truststore-note[specifically crafted ones can]
3640
--
3741

3842
** If the certificate is in PEM format, add the following information to the

x-pack/docs/en/settings/security-settings.asciidoc

+13
Original file line numberDiff line numberDiff line change
@@ -1231,6 +1231,19 @@ Password to the truststore.
12311231
`xpack.ssl.truststore.secure_password` (<<secure-settings,Secure>>)::
12321232
Password to the truststore.
12331233

1234+
[[pkcs12-truststore-note]]
1235+
[NOTE]
1236+
Storing trusted certificates in a PKCS#12 file, although supported, is
1237+
uncommon in practice. The {ref}/certutil.html[`elasticsearch-certutil`] tool,
1238+
as well as Java's `keytool`, are designed to generate PKCS#12 files that
1239+
can be used both as a keystore and as a truststore, but this may not be the
1240+
case for container files that are created using other tools. Usually,
1241+
PKCS#12 files only contain secret and private entries. To confirm that
1242+
a PKCS#12 container includes trusted certificate ("anchor") entries look for
1243+
`2.16.840.1.113894.746875.1.1: <Unsupported tag 6>` in the
1244+
`openssl pkcs12 -info` output, or `trustedCertEntry` in the
1245+
`keytool -list` output.
1246+
12341247
[[http-tls-ssl-settings]]
12351248
:ssl-prefix: xpack.security.http
12361249
:component: HTTP

0 commit comments

Comments
 (0)