From c5b5dc721bf4d6a248f8c74139e20f83a1bff875 Mon Sep 17 00:00:00 2001 From: Albert Zaharovits Date: Mon, 21 May 2018 02:49:34 +0300 Subject: [PATCH 1/4] PKCS12 trusted entry docs --- x-pack/docs/en/settings/security-settings.asciidoc | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/x-pack/docs/en/settings/security-settings.asciidoc b/x-pack/docs/en/settings/security-settings.asciidoc index 2c4df292857f3..f4326b510cf98 100644 --- a/x-pack/docs/en/settings/security-settings.asciidoc +++ b/x-pack/docs/en/settings/security-settings.asciidoc @@ -1225,6 +1225,13 @@ Password to the truststore. `xpack.ssl.truststore.secure_password` (<>):: Password to the truststore. +Note that storing trusted certificates in a PKCS#12 keystore, although supported, +is uncommon in practice. Usually, keystore files only contain secret and private +entries. To confirm that the passed keystore contains trusted certificate +("anchor") entries look for `2.16.840.1.113894.746875.1.1: ` +in the `openssl pkcs12 -info` output, or the `trustedCertEntry` in the +`keytool -list` output. + [[http-tls-ssl-settings]] :ssl-prefix: xpack.security.http :component: HTTP From 8d1a228aa4c274ec2847dbd8a73eca1c4fe69972 Mon Sep 17 00:00:00 2001 From: Albert Zaharovits Date: Mon, 28 May 2018 13:33:01 +0300 Subject: [PATCH 2/4] Specifically mention PKCS12 files and call out the certutil --- .../docs/en/settings/security-settings.asciidoc | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/x-pack/docs/en/settings/security-settings.asciidoc b/x-pack/docs/en/settings/security-settings.asciidoc index 8d4463d5ea546..9b4863df52249 100644 --- a/x-pack/docs/en/settings/security-settings.asciidoc +++ b/x-pack/docs/en/settings/security-settings.asciidoc @@ -1225,11 +1225,17 @@ Password to the truststore. `xpack.ssl.truststore.secure_password` (<>):: Password to the truststore. -Note that storing trusted certificates in a PKCS#12 keystore, although supported, -is uncommon in practice. Usually, keystore files only contain secret and private -entries. To confirm that the passed keystore contains trusted certificate -("anchor") entries look for `2.16.840.1.113894.746875.1.1: ` -in the `openssl pkcs12 -info` output, or the `trustedCertEntry` in the +[[pkcs12-trustore-note]] +[NOTE] +Storing trusted certificates in a PKCS#12 file, although supported, +is uncommon in practice. Elastic's `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 with 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: ` in the +`openssl pkcs12 -info` output, or the `trustedCertEntry` in the `keytool -list` output. [[http-tls-ssl-settings]] From a87501f7a9dc4a11b58ce5d266e627ef1c80d18c Mon Sep 17 00:00:00 2001 From: Albert Zaharovits Date: Mon, 28 May 2018 16:24:52 +0300 Subject: [PATCH 3/4] Added reference to note in 'Encrypting comms' --- .../node-certificates.asciidoc | 2 +- .../tls-transport.asciidoc | 9 ++++++--- .../docs/en/settings/security-settings.asciidoc | 16 ++++++++-------- 3 files changed, 15 insertions(+), 12 deletions(-) diff --git a/x-pack/docs/en/security/securing-communications/node-certificates.asciidoc b/x-pack/docs/en/security/securing-communications/node-certificates.asciidoc index 604355e21bf17..44ef8278fb968 100644 --- a/x-pack/docs/en/security/securing-communications/node-certificates.asciidoc +++ b/x-pack/docs/en/security/securing-communications/node-certificates.asciidoc @@ -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. diff --git a/x-pack/docs/en/security/securing-communications/tls-transport.asciidoc b/x-pack/docs/en/security/securing-communications/tls-transport.asciidoc index 2e20a20f907ef..b321608b3ef31 100644 --- a/x-pack/docs/en/security/securing-communications/tls-transport.asciidoc +++ b/x-pack/docs/en/security/securing-communications/tls-transport.asciidoc @@ -30,9 +30,12 @@ See <> 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 <>. -- ** If the certificate is in PEM format, add the following information to the diff --git a/x-pack/docs/en/settings/security-settings.asciidoc b/x-pack/docs/en/settings/security-settings.asciidoc index 9b4863df52249..e0e31c0fc3e5c 100644 --- a/x-pack/docs/en/settings/security-settings.asciidoc +++ b/x-pack/docs/en/settings/security-settings.asciidoc @@ -1227,15 +1227,15 @@ Password to the truststore. [[pkcs12-trustore-note]] [NOTE] -Storing trusted certificates in a PKCS#12 file, although supported, -is uncommon in practice. Elastic's `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 with 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 +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: ` in the -`openssl pkcs12 -info` output, or the `trustedCertEntry` in the +`openssl pkcs12 -info` output, or `trustedCertEntry` in the `keytool -list` output. [[http-tls-ssl-settings]] From e38301dbb187aad732c79d9bab1e52bd8b436431 Mon Sep 17 00:00:00 2001 From: Albert Zaharovits Date: Thu, 31 May 2018 21:43:54 +0300 Subject: [PATCH 4/4] Fix trustore typo and linking --- .../en/security/securing-communications/tls-transport.asciidoc | 3 ++- x-pack/docs/en/settings/security-settings.asciidoc | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/x-pack/docs/en/security/securing-communications/tls-transport.asciidoc b/x-pack/docs/en/security/securing-communications/tls-transport.asciidoc index b321608b3ef31..c186aebbe2433 100644 --- a/x-pack/docs/en/security/securing-communications/tls-transport.asciidoc +++ b/x-pack/docs/en/security/securing-communications/tls-transport.asciidoc @@ -35,7 +35,8 @@ 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 <>. +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 diff --git a/x-pack/docs/en/settings/security-settings.asciidoc b/x-pack/docs/en/settings/security-settings.asciidoc index 722b98faadb78..a98bca676152d 100644 --- a/x-pack/docs/en/settings/security-settings.asciidoc +++ b/x-pack/docs/en/settings/security-settings.asciidoc @@ -1225,7 +1225,7 @@ Password to the truststore. `xpack.ssl.truststore.secure_password` (<>):: Password to the truststore. -[[pkcs12-trustore-note]] +[[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,