Version: 6.x-23
This is an older version of Search Guard. Switch to Latest version
Community

Using the example PKI scripts

If you want to generate the certificates on your own machine, you can use the Search Guard example PKI scripts as a starting point. The scripts are shipped with Search Guard SSL and run on Linux or OS X.

You can use the scripts as-is, or you can edit the configuration files to tailor the certificates to your needs.

Prerequisites

The scripts use OpenSSL and the Java keytool for generating all required artifacts.

In order to find out if you have OpenSSL installed, open a terminal and type

openssl version

Make sure it’s version 1.0.1k or higher.

The keytool ships with the JDK itself and thus should be already available on your machine. Check it by calling

keytool

Which should print a list of available keytool commands. If this is not the case, check your JDK installation and make sure the keytool is on your PATH.

Generating the certificates

First download the Search Guard SSL source code onto your machine. You can either clone the repository, or download it as zip file. The repository is located here:

Search Guard SSL 6.x

The script to execute is ./example.sh, located in the folder example-pki-scripts. You might need to chmod the file before executing it.

If execution was successful, you’ll find the generated files and folders inside the example-pki-scripts folder. If for any reason you need to re-execute the script, execute ./clean.sh in the same directory first. This will remove all generated files automatically.

Generated artifacts

The script generates certificates in PEM, P12 and JKS format. You can use either for running Search Guard. The recommended format is PEM.

The following main certicates are generated:

  • Node certificates:
  • node-0-signed.pem / node-0.key.pem
  • node-1-signed.pem / node-1.key.pem
  • node-2-signed.pem / node-2.key.pem
  • Admin certificate:
  • kirk.crtfull.pem / kirk.key.pem
  • Client certificate:
  • spock.crtfull.pem / spock.key.pem

In order to configure the kirk certificate as admin certificate, add the following entry to elasticsearch.yml:

searchguard.authcz.admin_dn:
  - CN=kirk,OU=client,O=client,L=Test,C=DE

The script also generates certificates for Kibana, logstash and Beats. These can be used to secure the connection between said tools and Elasticsearch. This is optional but more secure.

The password for all private keys and keystore files is changeit.

The Root CA and Signing CA used to sign the certificates can be found in the folder example-pki-scripts/ca

Customizing the certificates

If you need to customize the certificates generated by the example PKI scripts, the following files are relevant:

example-pki-scripts/etc/root-ca.conf
example-pki-scripts/etc/signing-ca.conf

The example certificates are generated using a certificate chain. It consists of the Root CA, a signing CA and the actual certififcate. The two files stated above define the configuration of the Root CA and signing CA, especially the Distinguished Name(DN). You can change the DN in the following section:

[ ca_dn ]
0.domainComponent       = "com"
1.domainComponent       = "example"
organizationName        = "Example Com Inc."
organizationalUnitName  = "Example Com Inc. Root CA"
commonName              = "Example Com Inc. Root CA"

In order to customize the DN of the generated node-, admin-, and client-certificates, modify the following files:

gen_node_cert.sh
  Generates a node certificate

gen_client_node_cert.sh
  Generates a client certificate. 
  Certificates generated by this script can also be used as admin certificate  

You can change the DN, the hostname and the IP of the generated certificate by modifying the following sections in the respective files:

-dname "CN=$NODE_NAME.example.com, OU=SSL, O=Test, L=Test, C=DE" \
-ext san=dns:$NODE_NAME.example.com,dns:localhost,ip:127.0.0.1,oid:1.2.3.4.5.5

For gen_node_cert.sh, make sure you keep the oid:1.2.3.4.5.5 part! This OID value is used to identify node certificates in your cluster.


Not what you were looking for? Try the search.