From 42f9a990d17c220766614c7b8888bfd12143ce6c Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Thu, 15 Feb 2018 11:41:01 -0800 Subject: [PATCH] [DOCS] Split TLS instructions for HTTP and transport layers (elastic/x-pack-elasticsearch#3895) Original commit: elastic/x-pack-elasticsearch@77fe30f7d31fbc5b0b3cc29aecd7d6dd172f3b2f --- .../authentication/saml-guide.asciidoc | 6 +- .../node-certificates.asciidoc | 3 +- .../securing-elasticsearch.asciidoc | 11 +-- .../setting-up-ssl.asciidoc | 12 --- ...node-config.asciidoc => tls-http.asciidoc} | 85 +++++++---------- .../tls-transport.asciidoc | 94 +++++++++++++++++++ docs/en/setup/installing-xes.asciidoc | 2 +- 7 files changed, 137 insertions(+), 76 deletions(-) rename docs/en/security/securing-communications/{node-config.asciidoc => tls-http.asciidoc} (53%) create mode 100644 docs/en/security/securing-communications/tls-transport.asciidoc diff --git a/docs/en/security/authentication/saml-guide.asciidoc b/docs/en/security/authentication/saml-guide.asciidoc index 95c61bde99a0b..0567d00ffd953 100644 --- a/docs/en/security/authentication/saml-guide.asciidoc +++ b/docs/en/security/authentication/saml-guide.asciidoc @@ -85,7 +85,8 @@ If your {es} cluster is operating in production mode, then you must configure the HTTP interface to use SSL/TLS before you can enable SAML authentication. -See <> for instructions on how to do this. +For more information, see +{ref}/configuring-tls.html#tls-http[Encrypting HTTP Client Communications]. ==== Enable the Token Service @@ -708,7 +709,7 @@ If your {kib} instance is behind a proxy, you may also need to add configuration to tell {kib} how to form its public URL. This is needed because all SAML messages are exchanged via the user's web browser, so {kib} needs to know what URLs are used within the browser. In this case, the following settings should be -added to your `kibana.yml` configuration file: +added to your `kibana.yml` configuration file: [source, yaml] ------------------------------------------------------------ @@ -812,4 +813,3 @@ xpack.security.authc.realms.saml_eng: It is possible to have one or more {kib} instances that use SAML, while other instances use basic authentication against another realm type (e.g. <> or <>). - diff --git a/docs/en/security/securing-communications/node-certificates.asciidoc b/docs/en/security/securing-communications/node-certificates.asciidoc index 2caf3b3385da8..a621d6ecfba8d 100644 --- a/docs/en/security/securing-communications/node-certificates.asciidoc +++ b/docs/en/security/securing-communications/node-certificates.asciidoc @@ -82,8 +82,7 @@ directory on each node. For example, `/home/es/config/certs`. There is no need to copy the CA file to this directory. For each additional Elastic product that you want to configure, copy the -certificates to the relevant configuration directory. For more information, see -<>. +certificates to the relevant configuration directory. -- NOTE: If you choose not to use `certutil`, the certificates that you obtain must diff --git a/docs/en/security/securing-communications/securing-elasticsearch.asciidoc b/docs/en/security/securing-communications/securing-elasticsearch.asciidoc index 6525de35347f1..1e19ad7388efa 100644 --- a/docs/en/security/securing-communications/securing-elasticsearch.asciidoc +++ b/docs/en/security/securing-communications/securing-elasticsearch.asciidoc @@ -15,14 +15,13 @@ the cluster: . <>. -. <> to: -.. Identify itself using its signed certificate. -.. Required: Enable SSL on the transport layer. -.. Recommended: Enable SSL on the HTTP layer. -. Restart {es}. +. Configure each node to: +.. Required: <>. +.. Recommended: <>. For more information about encrypting communications across the Elastic Stack, see {xpack-ref}/encrypting-communications.html[Encrypting Communications]. include::node-certificates.asciidoc[] -include::node-config.asciidoc[] +include::tls-transport.asciidoc[] +include::tls-http.asciidoc[] diff --git a/docs/en/security/securing-communications/setting-up-ssl.asciidoc b/docs/en/security/securing-communications/setting-up-ssl.asciidoc index ff8da9a29ff5c..0c381c454d6ae 100644 --- a/docs/en/security/securing-communications/setting-up-ssl.asciidoc +++ b/docs/en/security/securing-communications/setting-up-ssl.asciidoc @@ -36,15 +36,3 @@ See <>. . Configure {es} for Apache Hadoop to use secured transport. See {hadoop-ref}/security.html[{es} for Apache Hadoop Security]. - -//The following sections can be removed after we clean up all links to these anchors. - -[[installing-node-certificates]] -==== Node Certificates - -See {ref}/configuring-tls.html#node-certificates[Generating Node Certificates]. - -[[enable-ssl]] -==== Enabling TLS in the Node Configuration - -See {ref}/configuring-tls.html#enable-ssl[Enabling TLS on {es} Nodes]. diff --git a/docs/en/security/securing-communications/node-config.asciidoc b/docs/en/security/securing-communications/tls-http.asciidoc similarity index 53% rename from docs/en/security/securing-communications/node-config.asciidoc rename to docs/en/security/securing-communications/tls-http.asciidoc index fe4618c1ce9d8..e6b1481483de6 100644 --- a/docs/en/security/securing-communications/node-config.asciidoc +++ b/docs/en/security/securing-communications/tls-http.asciidoc @@ -1,20 +1,30 @@ -[[enable-ssl]] -==== Enabling TLS on {es} Nodes +[role="xpack"] +[[tls-http]] +==== Encrypting HTTP Client Communications -Once you have the signed certificate, private key, and CA certificate you need -to modify the node configuration to enable Transport Layer Security (TLS/SSL). +When {security} is enabled, you can optionally use TLS to ensure that +communication between HTTP clients and the cluster is encrypted. -. Specify the information required to access the node's certificate. +NOTE: Enabling TLS on the HTTP layer is strongly recommended but is not required. +If you enable TLS on the HTTP layer in {es}, then you might need to make +configuration changes in other parts of the Elastic Stack and in any {es} +clients that you use. + +. If you have not done so already, <>. + +. Enable TLS and specify the information required to access the node’s +certificate. ** If the certificate is in PKCS#12 format, add the following information to the `elasticsearch.yml` file on each node: + -- -[source,yaml] ------------------------------------------------------------ -xpack.ssl.keystore.path: certs/elastic-certificates.p12 <1> -xpack.ssl.truststore.path: certs/elastic-certificates.p12 <2> ------------------------------------------------------------ +[source, yaml] +-------------------------------------------------- +xpack.security.http.ssl.enabled: true +xpack.security.http.ssl.keystore.path: certs/elastic-certificates.p12 <1> +xpack.security.http.ssl.truststore.path: certs/elastic-certificates.p12 <2> +-------------------------------------------------- <1> 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. @@ -29,9 +39,10 @@ should match the `keystore.path` value. -- [source, yaml] -------------------------------------------------- -xpack.ssl.key: /home/es/config/x-pack/node01.key <1> -xpack.ssl.certificate: /home/es/config/x-pack/node01.crt <2> -xpack.ssl.certificate_authorities: [ "/home/es/config/x-pack/ca.crt" ] <3> +xpack.security.http.ssl.enabled: true +xpack.security.http.ssl.key: /home/es/config/x-pack/node01.key <1> +xpack.security.http.ssl.certificate: /home/es/config/x-pack/node01.crt <2> +xpack.security.http.ssl.certificate_authorities: [ "/home/es/config/x-pack/ca.crt" ] <3> -------------------------------------------------- <1> The full path to the node key file. This must be a location within the {es} configuration directory. @@ -43,60 +54,30 @@ xpack.ssl.certificate_authorities: [ "/home/es/config/x-pack/ca.crt" ] <3> . If you secured the node's certificate with a password, add the password to your {es} keystore: + +** If the signed certificate is in PKCS#12 format, use the following commands: + -- [source,shell] ----------------------------------------------------------- -bin/elasticsearch-keystore add xpack.ssl.keystore.secure_password +bin/elasticsearch-keystore add xpack.security.http.ssl.keystore.secure_password -bin/elasticsearch-keystore add xpack.ssl.truststore.secure_password +bin/elasticsearch-keystore add xpack.security.http.ssl.truststore.secure_password ----------------------------------------------------------- -- -. Enable TLS on the transport networking layer to ensure that communication -between nodes is encrypted. Make the following changes in `elasticsearch.yml`: -+ --- -[source, yaml] --------------------------------------------------- -xpack.security.transport.ssl.enabled: true -xpack.security.transport.ssl.verification_mode: certificate <1> --------------------------------------------------- -<1> If you used the `--dns` or `--ip` options with the `certutil cert` command -and you want to enable strict hostname checking, set the verification mode to -`full`. --- - -. Optional: Enable TLS on the HTTP layer to ensure that communication between HTTP clients -and the cluster is encrypted. +** If the certificate is in PEM format, use the following commands: + -- -NOTE: Enabling TLS on the HTTP layer is strongly recommended but is not required. -If you enable TLS on the HTTP layer in {es}, then you might need to make -configuration changes in other parts of the Elastic Stack and in any {es} -clients that you use. - -Make the following changes in `elasticsearch.yml`: - -[source, yaml] --------------------------------------------------- -xpack.security.http.ssl.enabled: true --------------------------------------------------- +[source,shell] +----------------------------------------------------------- +bin/elasticsearch-keystore add xpack.security.http.ssl.secure_key_passphrase +----------------------------------------------------------- -- . Restart {es}. -+ --- -You must perform a full cluster restart. Nodes which are configured to use TLS -cannot communicate with nodes that are using unencrypted networking (and -vice-versa). After enabling TLS you must restart all nodes in order to maintain -communication across the cluster. --- NOTE: All TLS-related node settings are considered to be highly sensitive and therefore are not exposed via the {ref}/cluster-nodes-info.html#cluster-nodes-info[nodes info API] For more information about any of these settings, see <>. - -For information about configuring other products in the Elastic Stack, see -{xpack-ref}/ssl-tls.html[Setting Up TLS on a Cluster]. diff --git a/docs/en/security/securing-communications/tls-transport.asciidoc b/docs/en/security/securing-communications/tls-transport.asciidoc new file mode 100644 index 0000000000000..5553e6621ea34 --- /dev/null +++ b/docs/en/security/securing-communications/tls-transport.asciidoc @@ -0,0 +1,94 @@ +[role="xpack"] +[[tls-transport]] +==== Encrypting Communications Between Nodes in a Cluster + +The transport networking layer is used for internal communication between nodes +in a cluster. When {security} is enabled, you must use TLS to ensure that +communication between the nodes is encrypted. + +. <>. + +. Enable TLS and specify the information required to access the node’s +certificate. + +** If the signed certificate is in PKCS#12 format, add the following information to the +`elasticsearch.yml` file on each node: ++ +-- +[source,yaml] +----------------------------------------------------------- +xpack.security.transport.ssl.enabled: true +xpack.security.transport.ssl.verification_mode: certificate <1> +xpack.security.transport.ssl.keystore.path: certs/elastic-certificates.p12 <2> +xpack.security.transport.ssl.truststore.path: certs/elastic-certificates.p12 <3> +----------------------------------------------------------- +<1> If you used the `--dns` or `--ip` options with the `certutil cert` command +and you want to enable strict hostname checking, set the verification mode to +`full`. +<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 `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. +-- + +** If the certificate is in PEM format, add the following information to the +`elasticsearch.yml` file on each node: ++ +-- +[source, yaml] +-------------------------------------------------- +xpack.security.transport.ssl.enabled: true +xpack.security.transport.ssl.verification_mode: certificate <1> +xpack.security.transport.ssl.key: /home/es/config/x-pack/node01.key <2> +xpack.security.transport.ssl.certificate: /home/es/config/x-pack/node01.crt <3> +xpack.security.transport.ssl.certificate_authorities: [ "/home/es/config/x-pack/ca.crt" ] <4> +-------------------------------------------------- +<1> If you used the `--dns` or `--ip` options with the `certutil cert` command +and you want to enable strict hostname checking, set the verification mode to +`full`. +<2> The full path to the node key file. This must be a location within the + {es} configuration directory. +<3> The full path to the node certificate. This must be a location within the + {es} configuration directory. +<4> An array of paths to the CA certificates that should be trusted. These paths + must be a location within the {es} configuration directory. +-- + +. If you secured the node's certificate with a password, add the password to +your {es} keystore: + +** If the signed certificate is in PKCS#12 format, use the following commands: ++ +-- +[source,shell] +----------------------------------------------------------- +bin/elasticsearch-keystore add xpack.security.transport.ssl.keystore.secure_password + +bin/elasticsearch-keystore add xpack.security.transport.ssl.truststore.secure_password +----------------------------------------------------------- +-- + +** If the certificate is in PEM format, use the following commands: ++ +-- +[source,shell] +----------------------------------------------------------- +bin/elasticsearch-keystore add xpack.security.transport.ssl.secure_key_passphrase +----------------------------------------------------------- +-- + +. Restart {es}. ++ +-- +You must perform a full cluster restart. Nodes which are configured to use TLS +cannot communicate with nodes that are using unencrypted networking (and +vice-versa). After enabling TLS you must restart all nodes in order to maintain +communication across the cluster. +-- + +NOTE: All TLS-related node settings are considered to be highly sensitive and +therefore are not exposed via the +{ref}/cluster-nodes-info.html#cluster-nodes-info[nodes info API] For more +information about any of these settings, see <>. diff --git a/docs/en/setup/installing-xes.asciidoc b/docs/en/setup/installing-xes.asciidoc index 4a6c7e520229d..dded23e164e4e 100644 --- a/docs/en/setup/installing-xes.asciidoc +++ b/docs/en/setup/installing-xes.asciidoc @@ -161,7 +161,7 @@ information, see -- .. <>. -.. <>. +.. <>. . Start {es}. +