[DOCS] Adds instructions to extract files from a .p12 keystore (elast…

…ic#54981) (elastic#57229) * [DOCS] Adds instructions to extract files from a .p12 keystore * Update docs/user/security/securing-communications/index.asciidoc Co-Authored-By: Joe Portner <[email protected]> * Update docs/user/security/securing-communications/index.asciidoc Co-Authored-By: Joe Portner <[email protected]> * Update docs/user/security/securing-communications/index.asciidoc Co-Authored-By: Joe Portner <[email protected]> * Update docs/user/security/securing-communications/index.asciidoc Co-Authored-By: Joe Portner <[email protected]> * Update docs/user/security/securing-communications/index.asciidoc Co-Authored-By: Joe Portner <[email protected]> * Revised section to make it consistent with 7.6 * Format URL so it doesn't appear as a link Co-authored-by: Joe Portner <[email protected]> Co-authored-by: Joe Portner <[email protected]>
gchaps · Feb 10, 2020 · 3a732fe · 3a732fe
1 parent f551189
commit 3a732fe
Showing 1 changed file with 84 additions and 75 deletions.
diff --git a/docs/user/security/securing-communications/index.asciidoc b/docs/user/security/securing-communications/index.asciidoc
@@ -3,122 +3,131 @@
 ++++
 <titleabbrev>Encrypting communications</titleabbrev>
 ++++
+Secure Sockets Layer (SSL) and Transport Layer Security (TLS) provide encryption for data-in-transit. While these terms are often used
+interchangeably, {kib} supports only TLS, which supersedes the old SSL protocols.
 
-{kib} supports Transport Layer Security (TLS/SSL) encryption for client 
-requests. 
-//TBD: It is unclear what "client requests" are in this context. Is it just 
-// communication between the browser and the Kibana server or are we talking 
-// about other types of clients connecting to the Kibana server?
+Browsers send traffic to {kib} and {kib} sends traffic to {es}. These communication channels are configured separately to use TLS.
 
-If you are using {security} or a proxy that provides an HTTPS endpoint for {es}, 
-you can configure {kib} to access {es} via HTTPS. Thus, communications between 
-{kib} and {es} are also encrypted. 
+TLS requires X.509 certificates to authenticate the communicating parties and perform encryption of data-in-transit. Each certificate
+contains a public key and has an associated -- but separate -- private key; these keys are used for cryptographic operations. {kib}
+supports certificates and private keys in PEM format.
 
-. Configure {kib} to encrypt communications between the browser and the {kib}
-server:
-+
---
-NOTE: You do not need to enable {security} for this type of encryption. 
+[[configuring-tls-browser-kib]]
+==== Encrypting traffic between the browser and {kib}
 
---
+NOTE: You do not need to enable the {es} {security-features} for this type of encryption.
 
-.. Generate a server certificate for {kib}. 
+. Obtain a server certificate and private key for {kib}.
 +
 --
-//TBD: Can we provide more information about how they generate the certificate? 
-//Would they be able to use something like the elasticsearch-certutil command?
-You must either set the certificate's
-`subjectAltName` to the hostname, fully-qualified domain name (FQDN), or IP
-address of the {kib} server, or set the CN to the {kib} server's hostname
-or FQDN. Using the server's IP address as the CN does not work.
---
-
-.. Set the `server.ssl.enabled`, `server.ssl.key`, and `server.ssl.certificate` 
-properties in `kibana.yml`:
-+
---
-[source,yaml]
---------------------------------------------------------------------------------
-server.ssl.enabled: true
-server.ssl.key: /path/to/your/server.key
-server.ssl.certificate: /path/to/your/server.crt
---------------------------------------------------------------------------------
+{kib} will need to use this "server certificate" and corresponding private key when receiving connections from web browsers.
 
-After making these changes, you must always access {kib} via HTTPS. For example, 
-https://localhost:5601.
+When you obtain a server certificate, you must set its subject alternative name (SAN) correctly to ensure that modern web browsers with
+hostname verification will trust it. You can set one or more SANs to the {kib} server's fully-qualified domain name (FQDN), hostname, or IP
+address. When choosing the SAN, you should pick whichever attribute you will be using to connect to {kib} in your browser, which is likely
+the FQDN.
 
-// TBD: The reference information for server.ssl.enabled says it "enables SSL for 
-// outgoing requests from the Kibana server to the browser". Do we need to 
-// reiterate here that only one side of the communications is encrypted?
+You may choose to generate a certificate signing request (CSR) and private key using the {ref}/certutil.html[`elasticsearch-certutil`] tool.
 
-For more information, see <<settings,{kib} configuration settings>>.
---
+For example:
+[source,sh]
+--------------------------------------------------------------------------------
+bin/elasticsearch-certutil csr -name kibana-server -dns some-website.com,www.some-website.com
+--------------------------------------------------------------------------------
+This will produce a ZIP archive named `kibana-server.zip`. Extract that archive to obtain the PEM-formatted CSR (`kibana-server.csr`) and
+unencrypted private key (`kibana-server.key`). In this example, the CSR has a common name (CN) of `kibana-server`, a SAN of
+`some-website.com`, and another SAN of `www.some-website.com`.
 
-. Configure {kib} to connect to {es} via HTTPS:
-+
+NOTE: You will need to use a certificate authority (CA) to sign your CSR to obtain your server certificate. This certificate's signature
+will be verified by web browsers that are configured to trust the CA.
 --
-NOTE: To perform this step, you must 
-{ref}/configuring-security.html[enable the {es} {security-features}] or you 
-must have a proxy that provides an HTTPS endpoint for {es}. 
 
---
+. Configure {kib} to access the server certificate and private key.
 
-.. Specify the HTTPS protocol in the `elasticsearch.hosts` setting in the {kib}
-configuration file, `kibana.yml`:
+.. If your server certificate and private key are in PEM format:
 +
 --
+Specify your server certificate and private key in `kibana.yml`:
 [source,yaml]
 --------------------------------------------------------------------------------
-elasticsearch.hosts: ["https://<your_elasticsearch_host>.com:9200"]
+server.ssl.certificate: "/path/to/kibana-server.crt"
+server.ssl.key: "/path/to/kibana-server.key"
+--------------------------------------------------------------------------------
+If your private key is encrypted, add the decryption password to your <<secure-settings,{kib} keystore>>:
+[source,yaml]
+--------------------------------------------------------------------------------
+bin/kibana-keystore add server.ssl.keyPassphrase
 --------------------------------------------------------------------------------
 --
-
-.. If you are using your own CA to sign certificates for {es}, set the
-`elasticsearch.ssl.certificateAuthorities` setting in `kibana.yml` to specify
-the location of the PEM file.
+.. Otherwise, if your server certificate and private key are contained in a PKCS#12 file:
 +
 --
+You will need to extract the server certificate and private key in PEM format.
+[source,shell]
+----------------------------------------------------------
+openssl pkcs12 -in kibana-server.p12 -clcerts -nokeys -out kibana-server.crt
+openssl pkcs12 -in kibana-server.p12 -nocerts -nodes -out kibana-server.key
+----------------------------------------------------------
+This will produce a PEM-formatted server certificate (`kibana-server.crt`) and unencrypted private key (`kibana-server.key`). Then, specify
+these files in `kibana.yml` as described above.
+--
++
+For more information about settings for certificates and keys, see <<settings,{kib} configuration settings>>.
+. Configure {kib} to enable TLS for inbound connections.
++
+--
+Specify that TLS is used in `kibana.yml`:
 [source,yaml]
 --------------------------------------------------------------------------------
-elasticsearch.ssl.certificateAuthorities: /path/to/your/cacert.pem
+server.ssl.enabled: true
 --------------------------------------------------------------------------------
+--
+. Restart {kib}.
+After making these changes, you must always access {kib} via HTTPS. For example, `https://<your_kibana_host>.com`.
 
-Setting the `certificateAuthorities` property lets you use the default 
-`verificationMode` option of `full`. 
-//TBD: Is this still true? It isn't mentioned in https://www.elastic.co/guide/en/kibana/master/settings.html
+[[configuring-tls-kib-es]]
+==== Encrypting traffic between {kib} and {es}
 
-For more information, see <<settings,{kib} configuration settings>>. 
---
+NOTE: To perform this step, you must {ref}/configuring-security.html[enable the {es} {security-features}] or you must have a proxy that
+provides an HTTPS endpoint for {es}.
+
+. {ref}/configuring-tls.html#tls-http[Enable TLS on the HTTP layer in {es}].
 
-. (Optional) If the Elastic {monitor-features} are enabled, configure {kib} to 
-connect to the {es} monitoring cluster via HTTPS: 
+. Obtain the certificate authority (CA) certificate chain for {es}.
 +
 --
-NOTE: To perform this step, you must 
-{ref}/configuring-security.html[enable the {es} {security-features}] or you 
-must have a proxy that provides an HTTPS endpoint for {es}. 
+{kib} needs the appropriate CA certificate chain to properly establish trust when connecting to {es}.
+If you followed the {es} documentation for {ref}/configuring-tls.html#node-certificates[generating node certificates], you likely have a
+PKCS#12 file for each of your {es} nodes. You can extract the CA certificate chain from one of these files.
 
+[source,shell]
+--------------------------------------------------------------------------------
+openssl pkcs12 -in elastic-certificates.p12 -cacerts -nokeys -out elasticsearch-ca.pem
+--------------------------------------------------------------------------------
+This will produce a PEM-formatted file named `elasticsearch-ca.pem` that contains all CA certificates from the PKCS#12 file.
 --
-
-.. Specify the HTTPS URL in the `xpack.monitoring.elasticsearch.hosts` setting in 
-the {kib} configuration file, `kibana.yml`
+. Configure {kib} to trust the {es} CA certificate chain for the HTTP layer.
 +
 --
+Specify one or more PEM-formatted CA certificates in `kibana.yml`:
 [source,yaml]
 --------------------------------------------------------------------------------
-xpack.monitoring.elasticsearch.hosts: ["https://<your_monitoring_cluster>:9200"]
+elasticsearch.ssl.certificateAuthorities: ["/path/to/elasticsearch-ca.pem"]
 --------------------------------------------------------------------------------
+For more information about settings for certificates and keys, see <<settings,{kib} configuration settings>>.
 --
-
-.. Specify the `xpack.monitoring.elasticsearch.ssl.*` settings in the 
-`kibana.yml` file.
+. Configure {kib} to enable TLS for outbound connections to {es}.
 +
 --
-For example, if you are using your own certificate authority to sign
-certificates, specify the location of the PEM file in the `kibana.yml` file:
-
+Specify the HTTPS URL for {es} in `kibana.yml`:
 [source,yaml]
 --------------------------------------------------------------------------------
-xpack.monitoring.elasticsearch.ssl.certificateAuthorities: /path/to/your/cacert.pem
+elasticsearch.hosts: ["https://<your_elasticsearch_host>.com:9200"]
 --------------------------------------------------------------------------------
+NOTE: Using the HTTPS protocol results in a default `elasticsearch.ssl.verificationMode` option of `full`, which utilizes hostname
+verification. For more information about this setting, see <<settings,{kib} configuration settings>>.
+
 --
+If the Elastic {monitor-features} are enabled and you have set up a separate {es} monitoring cluster, you can also configure {kib} to
+connect to the monitoring cluster via HTTPS. The steps are the same as above, but each setting is prefixed by `xpack.monitoring.`. For
+example, `xpack.monitoring.elasticsearch.hosts`, `xpack.monitoring.elasticsearch.ssl.certificateAuthorities`, etc.