311 lines
14 KiB
Plaintext
311 lines
14 KiB
Plaintext
[[ssl-tls]]
|
|
=== Setting Up SSL/TLS on a Cluster
|
|
|
|
{security} enables you to encrypt traffic to, from and within your Elasticsearch
|
|
cluster. Connections are secured using Transport Layer Security (TLS), which is
|
|
commonly referred to as "SSL".
|
|
|
|
WARNING: Clusters that do not have encryption enabled send all data in plain text
|
|
including passwords.
|
|
|
|
To enable encryption, you need to perform the following steps on each node in
|
|
the cluster:
|
|
|
|
. <<installing-node-certificates, Generate a private key and X.509 certificate>>.
|
|
|
|
. <<configure-ssl, Configure the node>> to:
|
|
.. Identify itself using its signed certificate.
|
|
.. Enable SSL on the transport and HTTP layers.
|
|
|
|
. Restart Elasticsearch.
|
|
|
|
[[installing-node-certificates]]
|
|
==== 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, `certgen` has been included with {xpack}. This tool takes care of the generating
|
|
a CA and signing certificates with the CA. `certgen` can be used interactively or in a silent
|
|
mode through the use of an input file. The `certgen` tool also supports generation of certificate
|
|
signing requests (CSR), so that a commercial or organization specific CA may be used to sign
|
|
the certificates.
|
|
|
|
NOTE: If you choose not to use the `certgen`, 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 format. Although not required, it is highly recommended that the certificate contain
|
|
the dns name(s) and/or ip address(es) of the node so that hostname verification may be used.
|
|
|
|
[[generating-signed-certificates]]
|
|
===== Generating Certificates with `certgen`
|
|
|
|
The `certgen` tool can be used to generate a CA and signed certificates for your nodes. The tool
|
|
can be used interactively:
|
|
|
|
[listing]
|
|
....
|
|
bin/x-pack/certgen
|
|
This tool assists you in the generation of X.509 certificates and certificate
|
|
signing requests for use with SSL in the Elastic stack. Depending on the command
|
|
line option specified, you may be prompted for the following:
|
|
|
|
* The path to the output file
|
|
* The output file is a zip file containing the signed certificates and
|
|
private keys for each instance. If a Certificate Authority was generated,
|
|
the certificate and private key will also be included in the output file.
|
|
* Information about each instance
|
|
* An instance is any piece of the Elastic Stack that requires a SSL certificate.
|
|
Depending on your configuration, Elasticsearch, Logstash, Kibana, and Beats
|
|
may all require a certificate and private key.
|
|
* The minimum required value for each instance is a name. This can simply be the
|
|
hostname, which will be used as the Common Name of the certificate. A full
|
|
distinguished name may also be used.
|
|
* IP addresses and DNS names are optional. Multiple values can be specified as a
|
|
comma separated string. If no IP addresses or DNS names are provided, you may
|
|
disable hostname verification in your SSL configuration.
|
|
* Certificate Authority private key password
|
|
* The password may be left empty if desired.
|
|
|
|
Let's get started...
|
|
|
|
Please enter the desired output file [/home/es/config/x-pack/certificate-bundle.zip]:
|
|
Enter instance name: node01
|
|
Enter name for directories and files [node01]:
|
|
Enter IP Addresses for instance (comma-separated if more than one) []: 10.10.0.1
|
|
Enter DNS names for instance (comma-separated if more than one) []: node01.mydomain.com,node01
|
|
Would you like to specify another instance? Press 'y' to continue entering instance information: y
|
|
Enter instance name: node02
|
|
Enter name for directories and files [node02]:
|
|
Enter IP Addresses for instance (comma-separated if more than one) []: 10.10.0.2
|
|
Enter DNS names for instance (comma-separated if more than one) []: node02.mydomain.com
|
|
Would you like to specify another instance? Press 'y' to continue entering instance information:
|
|
Certificates written to /home/es/config/x-pack/certificate-bundle.zip
|
|
|
|
This file should be properly secured as it contains the private keys for all
|
|
instances and the certificate authority.
|
|
|
|
After unzipping the file, there will be a directory for each instance containing
|
|
the certificate and private key. Copy the certificate, key, and CA certificate
|
|
to the configuration directory of the Elastic product that they will be used for
|
|
and follow the SSL configuration instructions in the product guide.
|
|
|
|
For client applications, you may only need to copy the CA certificate and
|
|
configure the client to trust this certificate.
|
|
....
|
|
|
|
The usage of `certgen` above generates a zip file with the CA certificate, private key, two signed certificates and keys
|
|
in PEM format for `node01` and `node02`.
|
|
|
|
[[generating-csr]]
|
|
===== Generating Certificate Signing Requests with `certgen`
|
|
|
|
When using a commercial or organization specific CA, the `certgen` tool may be used to generate
|
|
certificate signing requests (CSR) for the nodes in your cluster:
|
|
|
|
[listing]
|
|
....
|
|
bin/x-pack/certgen -csr
|
|
This tool assists you in the generation of X.509 certificates and certificate
|
|
signing requests for use with SSL in the Elastic stack. Depending on the command
|
|
line option specified, you may be prompted for the following:
|
|
|
|
* The path to the output file
|
|
* The output file is a zip file containing the certificate signing requests
|
|
and private keys for each instance.
|
|
* Information about each instance
|
|
* An instance is any piece of the Elastic Stack that requires a SSL certificate.
|
|
Depending on your configuration, Elasticsearch, Logstash, Kibana, and Beats
|
|
may all require a certificate and private key.
|
|
* The minimum required value for each instance is a name. This can simply be the
|
|
hostname, which will be used as the Common Name of the certificate. A full
|
|
distinguished name may also be used.
|
|
* IP addresses and DNS names are optional. Multiple values can be specified as a
|
|
comma separated string. If no IP addresses or DNS names are provided, you may
|
|
disable hostname verification in your SSL configuration.
|
|
|
|
Let's get started...
|
|
|
|
Please enter the desired output file [/home/es/config/x-pack/csr-bundle.zip]:
|
|
Enter instance name: node01
|
|
Enter name for directories and files [node01]:
|
|
Enter IP Addresses for instance (comma-separated if more than one) []: 10.10.0.1
|
|
Enter DNS names for instance (comma-separated if more than one) []: node01.mydomain.com,node01
|
|
Would you like to specify another instance? Press 'y' to continue entering instance information: y
|
|
Enter instance name: node02
|
|
Enter name for directories and files [node02]:
|
|
Enter IP Addresses for instance (comma-separated if more than one) []: 10.10.0.2
|
|
Enter DNS names for instance (comma-separated if more than one) []: node02.mydomain.com
|
|
Would you like to specify another instance? Press 'y' to continue entering instance information:
|
|
Certificate signing requests written to /Users/jmodi/dev/tmp/elasticsearch-5.0.0-alpha5-SNAPSHOT/config/x-pack/csr-bundle.zip
|
|
|
|
This file should be properly secured as it contains the private keys for all
|
|
instances.
|
|
|
|
After unzipping the file, there will be a directory for each instance containing
|
|
the certificate signing request and the private key. Provide the certificate
|
|
signing requests to your certificate authority. Once you have received the
|
|
signed certificate, copy the signed certificate, key, and CA certificate to the
|
|
configuration directory of the Elastic product that they will be used for and
|
|
follow the SSL configuration instructions in the product guide.
|
|
....
|
|
|
|
The usage of `certgen` above generates a zip file with two CSRs and private
|
|
keys. The CSRs should be provided to the CA in order to obtain the signed
|
|
certificates. The signed certificates will need to be in PEM format in order to
|
|
be used.
|
|
|
|
[[certgen-silent]]
|
|
===== Using `certgen` in Silent Mode
|
|
|
|
`certgen` supports a silent mode of operation to enable easier batch operations. In order
|
|
to use this mode, a YAML file containing the information about the instances needs to be
|
|
created matching the format shown below:
|
|
|
|
[source, yaml]
|
|
--------------------------------------------------
|
|
instances:
|
|
- name: "node1" <1>
|
|
ip: <2>
|
|
- "192.0.2.1"
|
|
dns: <3>
|
|
- "node1.mydomain.com"
|
|
- name: "node2"
|
|
ip:
|
|
- "192.0.2.2"
|
|
- "198.51.100.1"
|
|
- name: "node3"
|
|
- name: "node4"
|
|
dns:
|
|
- "node4.mydomain.com"
|
|
- "node4.internal"
|
|
- name: "CN=node5,OU=IT,DC=mydomain,DC=com"
|
|
filename: "node5" <4>
|
|
--------------------------------------------------
|
|
<1> The name of the instance. This can be a simple string value or can be a Distinguished Name (DN). This is the only required field.
|
|
<2> An optional array of strings that represent IP Addresses for this instance. Both IPv4 and IPv6 values are allowed. The values will
|
|
be added as Subject Alternative Names.
|
|
<3> An optional array of strings that represent DNS names for this instance. The values will be added as Subject Alternative Names.
|
|
<4> The filename to use for this instance. This name will be the name of the directory in the zip file that this instance's files will
|
|
stored in and it will used be used in the naming of the files within the directory. This filename should not have an extension. Note: If
|
|
the `name` provided for the instance does not represent a valid filename, then the `filename` field must be present.
|
|
|
|
With the YAML file ready, the `certgen` tool can be used to generate certificates or certificate signing requests. Simply pass the file's
|
|
path to `certgen` using the `-in` option. For example:
|
|
|
|
[source, sh]
|
|
--------------------------------------------------
|
|
bin/x-pack/certgen -in instances.yml <1>
|
|
--------------------------------------------------
|
|
<1> Generates a CA certificate and private key in addition to certificates and private keys for the instances
|
|
contained in the YAML file. The other options to the tool can be specified in addition to the `-in` option. For all of the available
|
|
options, run `bin/x-pack/certgen -h`.
|
|
|
|
[[certgen-options]]
|
|
===== Command Line Options for `certgen`
|
|
|
|
`-out <file>`::
|
|
The path to the output file (`.zip`) that should be generated.
|
|
|
|
`-in <file>`::
|
|
Input file for running in <<certgen-silent, silent mode>>.
|
|
|
|
`-csr`::
|
|
Operate in <<generating-csr, Certificate Signing Request>> mode.
|
|
|
|
`-cert <file>`::
|
|
This option causes `certgen` to generate new instances certificates and keys
|
|
using an existing CA certificate (provided in the `file` argument).
|
|
+
|
|
_Not available in `-csr` mode._
|
|
|
|
`-key <file>`::
|
|
Provides the _private-key_ file for the CA certificate.
|
|
+
|
|
_Required whenever the `-cert` option is used._
|
|
|
|
`-pass <password>`::
|
|
Specifies the password for the CA private key.
|
|
If the `-key` option is provided, then this is the password for the existing
|
|
private key file.
|
|
Otherwise, it is the password that should be applied to the generated CA key.
|
|
+
|
|
_Not available in `-csr` mode._
|
|
|
|
`-p12 <password>`::
|
|
Generate a PKCS#12 (`.p12` or `.pfx`) container file for each of the instance
|
|
certificates and keys.
|
|
The generate file is protected by the supplied password (which may be blank).
|
|
+
|
|
_Not available in `-csr` mode._
|
|
|
|
`-dn <name>`::
|
|
The _Distinguished Name_ that should be used for the generated CA certificate.
|
|
+
|
|
_Not available in `-csr` mode, or with `-cert`._
|
|
|
|
`-keysize <bits>`::
|
|
The number of bits to be used in generates RSA keys (default `2048`).
|
|
|
|
`-days <n>`::
|
|
The number of days for which generated keys should be valid (default `1095`).
|
|
+
|
|
_Not available in `-csr` mode._
|
|
|
|
[[enable-ssl]]
|
|
==== Enabling SSL in the Node Configuration
|
|
|
|
Once you have the signed certificate, private key, and CA certificate you need to
|
|
modify the node configuration to enable SSL.
|
|
|
|
[[configure-ssl]]
|
|
To enable SSL, make the following changes in `elasticsearch.yml`:
|
|
|
|
. Specify the location of the node's keystore and the password(s) needed to
|
|
access the node's certificate. For example:
|
|
+
|
|
--
|
|
[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>
|
|
--------------------------------------------------
|
|
<1> The full path to the node key file. This must be a location within the
|
|
Elasticsearch configuration directory.
|
|
<2> The full path to the node certificate. This must be a location within the
|
|
Elasticsearch configuration directory.
|
|
<3> An array of paths to the CA certificates that should be trusted. These paths
|
|
must be a location within the Elasticsearch configuration directory.
|
|
--
|
|
|
|
. Enable SSL on the transport networking layer to ensure that communication
|
|
between nodes is encrypted:
|
|
+
|
|
[source, yaml]
|
|
--------------------------------------------------
|
|
xpack.security.transport.ssl.enabled: true
|
|
--------------------------------------------------
|
|
+
|
|
. Enable SSL on the HTTP layer to ensure that communication between HTTP clients
|
|
and the cluster is encrypted:
|
|
+
|
|
[source, yaml]
|
|
--------------------------------------------------
|
|
xpack.security.http.ssl.enabled: true
|
|
--------------------------------------------------
|
|
+
|
|
|
|
. Restart Elasticsearch.
|
|
|
|
NOTE: All SSL related node settings that are considered to be highly sensitive
|
|
and therefore are not exposed via the
|
|
{ref}/cluster-nodes-info.html#cluster-nodes-info[nodes info API].
|