diff --git a/docs/user/security/securing-communications/index.asciidoc b/docs/user/security/securing-communications/index.asciidoc index 6917a48909c7b..36d3dcb305234 100644 --- a/docs/user/security/securing-communications/index.asciidoc +++ b/docs/user/security/securing-communications/index.asciidoc @@ -3,122 +3,131 @@ ++++ Encrypting communications ++++ +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 <>. --- +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://.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 <>: +[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 <>. +. 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://.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 <>. --- +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://:9200"] +elasticsearch.ssl.certificateAuthorities: ["/path/to/elasticsearch-ca.pem"] -------------------------------------------------------------------------------- +For more information about settings for certificates and keys, see <>. -- - -.. 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://.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 <>. + -- +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.