Skip to content
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

[DOCS] Clarify not all PKCS12 usable as truststores #30750

Merged
merged 6 commits into from
May 31, 2018
Merged

[DOCS] Clarify not all PKCS12 usable as truststores #30750

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
c5b5dc7
PKCS12 trusted entry docs
albertzaharovits May 20, 2018
a1b4d3b
Merge branch 'master' into pkcs12-trustedEntries-docs
albertzaharovits May 28, 2018
8d1a228
Specifically mention PKCS12 files and call out the certutil
albertzaharovits May 28, 2018
a87501f
Added reference to note in 'Encrypting comms'
albertzaharovits May 28, 2018
bc54f07
Merge branch 'master' into pkcs12-trustedEntries-docs
albertzaharovits May 31, 2018
e38301d
Fix trustore typo and linking
albertzaharovits May 31, 2018
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
2 changes: 1 addition & 1 deletion x-pack/docs/en/security/securing-communications/node-certificates.asciidoc
View file
Open in desktop
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
9 changes: 6 additions & 3 deletions x-pack/docs/en/security/securing-communications/tls-transport.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,9 +30,12 @@ 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 <<pkcs12-trustore-note, specifically crafted ones can>>.
Copy link
Contributor Author

Choose a reason for hiding this comment

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

Not sure if the 'pkcs12-trustore-note' link is working correctly here. @lcawl can you please check if this is the proper way to link?

Copy link
Contributor

Choose a reason for hiding this comment

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

@albertzaharovits Things are a bit messy at the moment with OSS and X-Pack docs being split across 2 "books".
The pkcs12-trustore-note reference is in the ES docs (see https://www.elastic.co/guide/en/elasticsearch/reference/6.2/security-settings.html), but this page is in the X-Pack docs (see https://www.elastic.co/guide/en/elasticsearch/reference/6.2/configuring-tls.html#tls-transport).
So you need to do {ref}/security-settings.html#pkcs12-trustore-note

Can you also fix the spelling on truststore?

Copy link
Contributor

Choose a reason for hiding this comment

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

That's right, with the title in []: {ref}/security-settings.html#pkcs12-trustore-note[specially crafted ones] ...

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Thank you both for the explanation!

--

** 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
View file
Open in desktop
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-trustore-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