[DOCS] Split TLS instructions for HTTP and transport layers (elastic/…

…x-pack-elasticsearch#3895)

Original commit: elastic/x-pack-elasticsearch@77fe30f

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 <<enable-ssl>> 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.
 <<native-realm, Native>> or <<ldap-realm, LDAP>>).
-

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
-<<enable-ssl>>.
+certificates to the relevant configuration directory. 
 --
 
 NOTE: If you choose not to use `certutil`, the certificates that you obtain must

docs/en/security/securing-communications/securing-elasticsearch.asciidoc

@@ -15,14 +15,13 @@ the cluster:
 
 . <<node-certificates, Generate a private key and X.509 certificate>>.
 
-. <<enable-ssl, Configure each node>> 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: <<tls-transport,Enable TLS on the transport layer>>.
+.. Recommended: <<tls-http,Enable TLS on the HTTP layer>>.
 
 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[]

docs/en/security/securing-communications/setting-up-ssl.asciidoc

@@ -36,15 +36,3 @@ See <<java-clients>>.
 
 . 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].

docs/en/security/securing-communications/node-config.asciidoc → 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, <<node-certificates,generate node certificates>>.
+
+. 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 <<security-settings>>.
-
-For information about configuring other products in the Elastic Stack, see
-{xpack-ref}/ssl-tls.html[Setting Up TLS on a Cluster].

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.
+
+. <<node-certificates,Generate node certificates>>.
+
+. 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 <<security-settings>>.

docs/en/setup/installing-xes.asciidoc

@@ -161,7 +161,7 @@ information, see
 --
 .. <<node-certificates,Generate node certificates for each of your {es} nodes>>.
 
-.. <<enable-ssl, Enable TLS on each {es} node>>.
+.. <<tls-transport, Enable TLS on each {es} node>>.
 
 . Start {es}.
 +