Version: 7.x-51.0.0

TLS for production environments

When moving Search Guard to production you most likely want to use certificates generated by your own PKI infrastructure. This chapter describes the different certificate types and how to generate and configure them.

Supported formats

Search Guard supports certificates in the following formats:

  • X509 PEM certificates and PKCS8 private keys
  • Keystores and truststores in JKS or PKCS12/PFX format

Types of certificates

Search Guard distinguishes between the following types of certificates

  • Node certificates
  • Client certificates
  • Admin certificates

Node certificates are used to identify and secure traffic between Elasticsearch nodes on the transport layer (inter-node traffic). For this kind of traffic, no permission checks are applied, i.e. every request is allowed. Therefore, these certificates must meet some special requirements. See below for details and options.

Client certificates are regular TLS certificates without any special requirements. They are used to identify Elasticsearch clients on the REST and transport layer. They can be used for HTTP client certificate authentication or when using a Java Transport Client on transport layer.

Admin certificates are client certificates that have elevated rights to perform administrative tasks. You need an admin certificate to change the Search Guard configuration via the sgadmin command line tool, or to use the REST management API. Admin certificates are configured in elasticsearch.yml by simply stating their DN(s). You can use any valid client certificate as an admin certificate.

Note: Do not use a node certificate as admin certificate! Node and admin certificates must always be kept separate.

Node certificates

Search Guard needs to securely and reliably identify internal communication between Elasticsearch nodes (inter-node traffic). This communication happens for example if one node receives a GET request on the HTTP layer, but needs to forward it to another node that holds the actual data.

Search Guard offers several ways of identifying inter-node traffic. Depending on your PKI setup and capabilities, you can choose from one of the following methods.

Listing DNs of node certificates

The simplest way of configuring node certificates is to list the DNs of these certificates in elasticsearch.yml. Wildcards and regular expressions are supported:

  - ',OU=SSL,O=Test,L=Test,C=DE'
  - 'CN=*,OU=SSL,O=Test,L=Test,C=DE'
  - 'CN=elk-devcluster*'
  - '/CN=.*regex/'

All certificate DNs listed here are considered valid node certificates.

Using an OID value as SAN entry

This is the default setting of Search Guard when no searchguard.nodes_dn is specified. It is also used as fallback if the certificate’s DN does not match any DN configured in searchguard.nodes_dn.

OID stands for an object identifier and in this context it is used to identify an X.509 certificate extension, i.e. an additional data field stored in the certificate, which is not predefined by the standard.

If you want to learn more about OIDs in TLS certificates, refer to Red Hats Standard X.509 v3 Certificate Extension Reference.

The OID is defined in the Subject Alternative Name (SAN) section of the certificate. Unless searchguard.nodes_dn is configured it must have the default value for node certificates (see below how to use a custom value). If this value is found, the certificate is considered to be a valid node certificate.

The OID approach is more flexible than listing the DNs individually: All certificates containing this OID value in the SAN field are considered valid node certificates, so you can add new nodes on the fly without changing the searchguard.nodes_dn setting.

If you want to use this approach, make sure that your CSR includes oid: in the SAN field.

Using a custom OID value

If you cannot set the OID to the default value, but you are able to use a different value, you can configure this value in elasticsearch.yml by setting:

searchguard.cert.oid: <String>

Custom implementation

You can also provide your own implementation to identify inter-node traffic.

Extended key usage settings

A node certificate is used for server authentication and client authentication:

  • If a node issues an request to another node, it acts like a client, requesting data from a server.

  • If a node receives requests from another node, it acts like a server, accepting requests from the client node.

Therefore, for node certificates the extended key usage settings must include both serverAuth and clientAuth:

#3: ObjectId: Criticality=false
ExtendedKeyUsages [

Special characters and whitespaces

Search Guard uses the String Representation of Distinguished Names (RFC1779) when validating node certificates.

If parts of your DN contain special characters, for example a comma, make sure it is escaped properly in your searchguard.nodes_dn configuration, for example:

  - ',OU=SSL,O=My\, Test,L=Test,C=DE'

Omit whitespaces between the individual parts of the DN. Instead of:

  - ', OU=SSL, O=MyTest, L=Test,C=DE'


  - ',OU=SSL,O=MyTest,L=Test,C=DE'

emailAddress Fields

Using the emailAddress as part of the DN is deprecated. It is recommended to add the email as SAN entry to the certificate instead.

Working with aliases

While it is common to have separate files for storing the trusted root certificates (“truststore”) and the client certificate, technically speaking there is no reason to do so. Means, you can also store the root certificates, intermediate certificates and client certificates in the same file.

In this case you can work with aliases to specify which certificate in your keystore should be used for what purpose.

When importing certificates in your keystore, you can set an alias name like:

keytool -importcert -file cert.pem -keystore keystore.jks -alias "myalias"

You can later use this alias in the Search Guard TLS configuration to refer to exactly this certificate (or certificate chain), for example:

searchguard.ssl.transport.keystore_filepath keystore.jks
searchguard.ssl.transport.keystore_alias: myalias

Client and admin certificates

There are no special requirements for client and admin certificates. So any certificate signed by the Root CA or intermediate CA can be used.

Admin certificates have elevated permissions, including the permission to change the Search Guard index. To assign these elevated permissions to a certificate, simply list them in elasticsearch.yml:

  - CN=admin,OU=SSL,O=Test,L=Test,C=DE

Note: For security reasons, wildcards and regular expressions are not supported for admin certificates!

Disable TLS Client Renegotiation

Secure Client-Initiated Renegotiation is disabled by default, because it could be used for denial of service attacks on the HTTP port. If you want to enable Client-Initiated Renegotiation, add the following line to config/jvm.options:


Disable TLS versions and weak ciphers

You can control the enabled ciphers and TLS protocols by the following configuration keys in elasticsearch.yml:

  - "TLSv1.1"
  - "TLSv1.2"

See the TLS configuration chapter for more details.

Not what you were looking for? Try the search.