Configure SSL/TLS

By default, Enterprise Search does not enable TLS (Transport Layer Security) for incoming HTTP connections.

To enable SSL/TLS, set the following configuration settings:

ent_search.ssl.enabled: true
ent_search.ssl.keystore.path: "/path/to/keystore.jks"
ent_search.ssl.keystore.password: "changeme"
ent_search.ssl.keystore.key_password: "changeme"
ent_search.external_url: https://localhost:3002

See below for more details on specific settings.

In the above example, keystore.jks is a Java KeyStore file.

You can create a Java KeyStore file using the keytool utility, which is included with the JVM. If you are using the Elastic provided Docker image, the keytool utility is available at /usr/bin/keytool within the container. See keytool - Key and Certificate Management Tool in the Java documentation for more details on the usage of this tool.

In a production scenario, you would merge your private key (private.key) and your SSL certificate (certificate.crt) into the PKCS12 format and then convert it to a Java keystore by using the following commands:

# Convert the existing certificate and the private key to a PKCS12 file
openssl pkcs12 -export \
  -in certificate.crt \
  -inkey private.key \
  -out keystore.p12 \
  -name ent-search

# Create the Java keystore from the PKCS12 file
keytool -importkeystore \
  -destkeystore keystore.jks \
  -srckeystore keystore.p12 \
  -srcstoretype PKCS12 \
  -storepass changeme
  -alias ent-search

In a development environment (do not use this in production), you can use they they keytool command to create a self-signed certificate and add it to a keystore for use with a server running on localhost:

keytool -genkey -alias server-alias -keyalg RSA \
  -storepass changeme -keypass changeme -keystore keystore.jks \
  -dname 'CN=localhost, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown'

Note that the values used in -keypass changeme and -storepass changeme correspond directly to the values that must be set for ent_search.ssl.keystore.key_password and ent_search.ssl.keystore.password, respectively.

If you are using a custom SSL certificate for your Enterprise Search deployment, you will have to configure Kibana accordingly to make sure it trusts your custom SSL certificate by adding your custom Certificate Authority (CA) to Kibana configuration.

The Enterprise Search SSL configuration in Kibana is controlled by the following options:

Here is an example snippet from a kibana.yml file used on a deployment with Enterprise Search:

enterpriseSearch.host: https://some-host.tld:3002
enterpriseSearch.ssl.verificationMode: certificate
enterpriseSearch.ssl.certificateAuthorities:
  - /path/to/your/ca.pem

Enterprise Search does not support requests from the Enterprise Search Server to Kibana using a custom Certificate Authority.

In addition to the above instructions, you may want to avoid having your users specify a port number when visiting Enterprise Search. In order to allow your users to make use of HTTPS only, you can set:

ent_search.listen_port: 443
ent_search.external_url: https://my_host.my_domain.com:443
ent_search.ssl.redirect_http_from_port: 80

This will bind your server to port 443 (the default HTTPS traffic port), and will ensure that traffic routed to port 80 (the default HTTP port) will redirect to 443. This ensures that any visitor to my_host.my_domain.com will make use of TLS.

This error may occur if you’re using a legacy configuration that specifies keys and certificates separately, and it is a known JRuby bug: https://github.com/jruby/jruby-openssl/issues/104. It is recommended that you use a Java KeyStore file as explained above. If this is not possible, endeavor to remove the "Bag Attributes" from your keyfile. This can be done by generating your keyfile like:

openssl pkcs12 -in keystore.p12  -nodes -nocerts -passin pass:changeme | openssl rsa -out my_store.key

You can also manually remove the "Bag Attributes" portion of your keyfile with a text editor.