Skip to content

Commit

Permalink
[DOCS] Clarify not all PKCS12 usable as truststores (#30750)
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
albertzaharovits authored May 31, 2018
1 parent b225f5e commit d9ab146
Show file tree
Hide file tree
Showing 3 changed files with 21 additions and 4 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
TLS requires X.509 certificates to perform encryption and authentication of the
application that is being communicated with. In order for the communication
between nodes to be truly secure, the certificates must be validated. The
recommended approach for validating certificate authenticity in a {es} cluster
recommended approach for validating certificate authenticity in an {es} cluster
is to trust the certificate authority (CA) that signed the certificate. By doing
this, as nodes are added to your cluster they just need to use a certificate
signed by the same CA and the node is automatically allowed to join the cluster.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -30,9 +30,13 @@ See <<ssl-tls-settings, `xpack.ssl.verification_mode`>> for a description of the
<2> If you created a separate certificate for each node, then you might need to
customize this path on each node. If the filename matches the node name, you can
use the `certs/${node.name}.p12` format, for example.
<3> The `elasticsearch-certutil` output includes the CA certificate inside the
PKCS#12 keystore, therefore the keystore can also be used as the truststore.
This name should match the `keystore.path` value.
<3> The `elasticsearch-certutil` outputs a PKCS#12 keystore which includes the
CA certificate as a trusted certificate entry. This allows for the keystore to
also be used as a truststore. In this case, the path value should match
the `keystore.path` value.
Note, however, that this is not the general rule. There are keystores that cannot be
used as trustores, only
{ref}/security-settings.html#pkcs12-truststore-note[specifically crafted ones can]
--

** If the certificate is in PEM format, add the following information to the
Expand Down
13 changes: 13 additions & 0 deletions x-pack/docs/en/settings/security-settings.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -1225,6 +1225,19 @@ Password to the truststore.
`xpack.ssl.truststore.secure_password` (<<secure-settings,Secure>>)::
Password to the truststore.

[[pkcs12-truststore-note]]
[NOTE]
Storing trusted certificates in a PKCS#12 file, although supported, is
uncommon in practice. The {ref}/certutil.html[`elasticsearch-certutil`] tool,
as well as Java's `keytool`, are designed to generate PKCS#12 files that
can be used both as a keystore and as a truststore, but this may not be the
case for container files that are created using other tools. Usually,
PKCS#12 files only contain secret and private entries. To confirm that
a PKCS#12 container includes trusted certificate ("anchor") entries look for
`2.16.840.1.113894.746875.1.1: <Unsupported tag 6>` in the
`openssl pkcs12 -info` output, or `trustedCertEntry` in the
`keytool -list` output.

[[http-tls-ssl-settings]]
:ssl-prefix: xpack.security.http
:component: HTTP
Expand Down

0 comments on commit d9ab146

Please sign in to comment.