Configure SSL/TLS

Configure SSL/TLSedit

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.

Create the Java KeyStoreedit

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.

Configure Kibana to Trust Your SSL Certificate Authorityedit

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:

  • enterpriseSearch.ssl.certificateAuthorities – used to configure a list of custom Certificate Authority (CA) certificates to be used for validating certificates presented by Enterprise Search. You need to set this to the CA certificate (in a PEM format) you used to generate your custom Enterprise Search SSL certificate.
  • enterpriseSearch.ssl.verificationMode – used to control the level of SSL certificate validation for connections from Kibana to Enterprise Search. Possible values are:

    • full (default, both SSL certificate and host name are verified)
    • certificate (only SSL certificate validation is performed, hostname is not checked)
    • none (SSL validation is disabled entirely, useful for development only).

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

If you are using a self-signed SSL certificate (without a custom Certificate Authority), the only way to make Kibana work with it is by disabling SSL verification entirely (by setting enterpriseSearch.ssl.verificationMode: none).

Do not use this method in production!

Enterprise Search requests to Kibana using custom CAsedit

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

Hosting on the default HTTPS portedit

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.

Troubleshootingedit

  • java.lang.ClassCastException: org.bouncycastle.asn1.DERApplicationSpecific cannot be cast to org.bouncycastle.asn1.ASN1Sequence

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.