This is an older version of Search Guard. Switch to Latest version
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.
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.
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:
searchguard.nodes_dn: - 'CN=node.other.com,OU=SSL,O=Test,L=Test,C=DE' - 'CN=*.example.com,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
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.
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
18.104.22.168.5.5 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
If you want to use this approach, make sure that your CSR includes
oid:22.214.171.124.5.5 in the
Using a custom OID value
If you cannot set the
OID to the default value
126.96.36.199.5.5, but you are able to use a different value, you can configure this value in
elasticsearch.yml by setting:
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
#3: ObjectId: 188.8.131.52 Criticality=false ExtendedKeyUsages [ serverAuth clientAuth ]
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:
searchguard.nodes_dn: - 'CN=node.other.com,OU=SSL,O=My\, Test,L=Test,C=DE'
Omit whitespaces between the individual parts of the DN. Instead of:
searchguard.nodes_dn: - 'CN=node.other.com, OU=SSL, O=MyTest, L=Test,C=DE'
searchguard.nodes_dn: - 'CN=node.other.com,OU=SSL,O=MyTest,L=Test,C=DE'
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
searchguard.authcz.admin_dn: - 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
searchguard.ssl.http.enabled_ciphers: - "TLS_DHE_RSA_WITH_AES_256_CBC_SHA" - "TLS_DHE_DSS_WITH_AES_128_CBC_SHA256" searchguard.ssl.http.enabled_protocols: - "TLSv1.1" - "TLSv1.2"
See the TLS configuration chapter for more details.