This is an older version of Search Guard. Switch to Latest version
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:
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.
Additional resources