Encrypting Communications in Elasticsearch

WARNING: Version 6.2 of Elasticsearch has passed its EOL date.

This documentation is no longer being maintained and may be removed. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.

› › ›

« Configuring Security in Elasticsearch Encrypting Communications in an Elasticsearch Docker Image »

X-Pack security enables you to encrypt traffic to, from, and within your Elasticsearch cluster. Connections are secured using Transport Layer Security (TLS/SSL).

Clusters that do not have encryption enabled send all data in plain text including passwords and will not be able to install a license that enables X-Pack security.

To enable encryption, you need to perform the following steps on each node in the cluster:

Install X-Pack into Elasticsearch.
Generate a private key and X.509 certificate.
Configure each node to:
1. Required: Enable TLS on the transport layer.
2. Recommended: Enable TLS on the HTTP layer.

For more information about encrypting communications across the Elastic Stack, see Encrypting Communications.

Generating Node Certificates

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 Elasticsearch 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. Additionally, it is recommended that the certificates contain subject alternative names (SAN) that correspond to the node’s IP address and DNS name so that hostname verification can be performed.

In order to simplify the process of generating certificates for the Elastic Stack, a command line tool, certutil has been included with X-Pack. This tool takes care of generating a CA and signing certificates with the CA. certutil can be used interactively or in a silent mode through the use of an input file. The certutil tool also supports generation of certificate signing requests (CSR), so that a commercial- or organization-specific CA can be used to sign the certificates. For example:

Optional: Create a certificate authority for your Elasticsearch cluster.

For example, use the certutil ca command:
```
bin/x-pack/certutil ca
```
You can configure the cluster to trust all nodes that have a certificate that has been signed by this CA.

The command outputs a single file, with a default name of elastic-stack-ca.p12. This file is a PKCS#12 keystore that contains the public certificate for your CA and the private key that is used to sign the certificates for each node.

The certutil command also prompts you for a password to protect the file and key. If you plan to add more nodes to your cluster in the future, retain a copy of the file and remember its password.
Generate a certificate and private key for each node in your cluster.

For example, use the certutil cert command:
```
bin/x-pack/certutil cert --ca elastic-stack-ca.p12
```
The output is a single PKCS#12 keystore that includes the node certificate, node key, and CA certificate.

You are also prompted for a password. You can enter a password for your certificate and key, or you can leave the password blank by pressing Enter.

By default certutil generates certificates that have no hostname information in them (that is, they do not have any Subject Alternative Name fields). This means that you can use the certificate for every node in your cluster, but you must turn off hostname verification as shown in the configuration below.

If you want to use hostname verification within your cluster, run the certutil cert command once for each of your nodes and provide the --name, --dns and --ip options.

You should secure the output files, since they contain the private keys for your instance.

Alternatively, if you want to use a commercial or organization-specific CA, you can use the certutil csr command to generate certificate signing requests (CSR) for the nodes in your cluster. For more information, see certutil.
Copy the node certificate to the appropriate locations.

Copy the applicable .p12 file into a directory within the Elasticsearch configuration 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.

If you choose not to use certutil, the certificates that you obtain must allow for both clientAuth and serverAuth if the extended key usage extension is present. The certificates need to be in PEM or PKCS#12 format. Although not required, it is highly recommended that the certificate contain the DNS names and/or IP addresses of the node so that hostname verification can be used.

Encrypting Communications Between Nodes in a Cluster

The transport networking layer is used for internal communication between nodes in a cluster. When X-Pack security is enabled, you must use TLS to ensure that communication between the nodes is encrypted.

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:

xpack.security.transport.ssl.enabled: true
xpack.security.transport.ssl.verification_mode: certificate 
xpack.security.transport.ssl.keystore.path: certs/elastic-certificates.p12 
xpack.security.transport.ssl.truststore.path: certs/elastic-certificates.p12

	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`. See `xpack.ssl.verification_mode` for a description of these values.
	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.
	The `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 specifically crafted ones can.

If the certificate is in PEM format, add the following information to the elasticsearch.yml file on each node:

xpack.security.transport.ssl.enabled: true
xpack.security.transport.ssl.verification_mode: certificate 
xpack.security.transport.ssl.key: /home/es/config/x-pack/node01.key 
xpack.security.transport.ssl.certificate: /home/es/config/x-pack/node01.crt 
xpack.security.transport.ssl.certificate_authorities: [ "/home/es/config/x-pack/ca.crt" ]

	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`. See `xpack.ssl.verification_mode` for a description of these values.
	The full path to the node key file. This must be a location within the Elasticsearch configuration directory.
	The full path to the node certificate. This must be a location within the Elasticsearch configuration directory.
	An array of paths to the CA certificates that should be trusted. These paths must be a location within the Elasticsearch configuration directory.

If you secured the node’s certificate with a password, add the password to your Elasticsearch keystore:

If the signed certificate is in PKCS#12 format, use the following commands:

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:

bin/elasticsearch-keystore add xpack.security.transport.ssl.secure_key_passphrase

Restart Elasticsearch.

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.

All TLS-related node settings are considered to be highly sensitive and therefore are not exposed via the nodes info API For more information about any of these settings, see Security settings.

Encrypting HTTP Client Communications

When X-Pack security is enabled, you can optionally use TLS to ensure that communication between HTTP clients and the cluster is encrypted.

Enabling TLS on the HTTP layer is strongly recommended but is not required. If you enable TLS on the HTTP layer in Elasticsearch, then you might need to make configuration changes in other parts of the Elastic Stack and in any Elasticsearch clients that you use.

If you have not done so already, 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:

xpack.security.http.ssl.enabled: true
xpack.security.http.ssl.keystore.path: certs/elastic-certificates.p12 
xpack.security.http.ssl.truststore.path: certs/elastic-certificates.p12

	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.
	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:

xpack.security.http.ssl.enabled: true
xpack.security.http.ssl.key:  /home/es/config/x-pack/node01.key 
xpack.security.http.ssl.certificate: /home/es/config/x-pack/node01.crt 
xpack.security.http.ssl.certificate_authorities: [ "/home/es/config/x-pack/ca.crt" ]

	The full path to the node key file. This must be a location within the Elasticsearch configuration directory.
	The full path to the node certificate. This must be a location within the Elasticsearch configuration directory.
	An array of paths to the CA certificates that should be trusted. These paths must be a location within the Elasticsearch configuration directory.

If you secured the node’s certificate with a password, add the password to your Elasticsearch keystore:
- If the signed certificate is in PKCS#12 format, use the following commands:
```
bin/elasticsearch-keystore add xpack.security.http.ssl.keystore.secure_password

bin/elasticsearch-keystore add xpack.security.http.ssl.truststore.secure_password
```
- If the certificate is in PEM format, use the following commands:
```
bin/elasticsearch-keystore add xpack.security.http.ssl.secure_key_passphrase
```
Restart Elasticsearch.

All TLS-related node settings are considered to be highly sensitive and therefore are not exposed via the nodes info API For more information about any of these settings, see Security settings.

« Configuring Security in Elasticsearch Encrypting Communications in an Elasticsearch Docker Image »