Rename certutil

This commit renames certutil to elasticsearch-certutil.
This commit is contained in:
Jason Tedor 2018-04-10 18:57:08 -04:00 committed by Ryan Ernst
parent a6b4682711
commit 03ffd16921
10 changed files with 62 additions and 57 deletions

View File

@ -1,16 +1,16 @@
[role="xpack"] [role="xpack"]
[[certutil]] [[certutil]]
== certutil == elasticsearch-certutil
The `certutil` command simplifies the creation of certificates for use with The `elasticsearch-certutil` command simplifies the creation of certificates for
Transport Layer Security (TLS) in the Elastic Stack. use with Transport Layer Security (TLS) in the Elastic Stack.
[float] [float]
=== Synopsis === Synopsis
[source,shell] [source,shell]
-------------------------------------------------- --------------------------------------------------
bin/x-pack/certutil bin/elasticsearch-certutil
( (
(ca [--ca-dn <name>] [--days <n>] [--pem]) (ca [--ca-dn <name>] [--days <n>] [--pem])
@ -31,9 +31,9 @@ bin/x-pack/certutil
[float] [float]
=== Description === Description
You can specify one of the following modes: `ca`, `cert`, `csr`. The `certutil` You can specify one of the following modes: `ca`, `cert`, `csr`. The
command also supports a silent mode of operation to enable easier batch `elasticsearch-certutil` command also supports a silent mode of operation to
operations. enable easier batch operations.
[float] [float]
[[certutil-ca]] [[certutil-ca]]
@ -199,7 +199,7 @@ format:
[source, sh] [source, sh]
-------------------------------------------------- --------------------------------------------------
bin/x-pack/certutil ca bin/elasticsearch-certutil ca
-------------------------------------------------- --------------------------------------------------
You are prompted for an output filename and a password. Alternatively, you can You are prompted for an output filename and a password. Alternatively, you can
@ -210,7 +210,7 @@ CA. For example:
[source, sh] [source, sh]
-------------------------------------------------- --------------------------------------------------
bin/x-pack/certutil cert --ca elastic-stack-ca.p12 bin/elasticsearch-certutil cert --ca elastic-stack-ca.p12
-------------------------------------------------- --------------------------------------------------
You are prompted for the CA password and for an output filename and password. You are prompted for the CA password and for an output filename and password.
@ -223,7 +223,7 @@ product that you want to configure. For more information, see
[float] [float]
[[certutil-silent]] [[certutil-silent]]
==== Using `certutil` in Silent Mode ==== Using `elasticsearch-certutil` in Silent Mode
To use the silent mode of operation, you must create a YAML file that contains To use the silent mode of operation, you must create a YAML file that contains
information about the instances. It must match the following format: information about the instances. It must match the following format:
@ -261,13 +261,13 @@ the names of the files within the directory. This filename should not have an
extension. Note: If the `name` provided for the instance does not represent a extension. Note: If the `name` provided for the instance does not represent a
valid filename, then the `filename` field must be present. valid filename, then the `filename` field must be present.
When your YAML file is ready, you can use the `certutil` command to generate When your YAML file is ready, you can use the `elasticsearch-certutil` command
certificates or certificate signing requests. Simply use the `--in` parameter to to generate certificates or certificate signing requests. Simply use the `--in`
specify the location of the file. For example: parameter to specify the location of the file. For example:
[source, sh] [source, sh]
-------------------------------------------------- --------------------------------------------------
bin/x-pack/certutil cert --silent --in instances.yml --out test1.zip --pass testpassword bin/elasticsearch-certutil cert --silent --in instances.yml --out test1.zip --pass testpassword
-------------------------------------------------- --------------------------------------------------
This command generates a compressed `test1.zip` file. After you decompress the This command generates a compressed `test1.zip` file. After you decompress the
@ -281,7 +281,7 @@ example:
[source, sh] [source, sh]
-------------------------------------------------- --------------------------------------------------
bin/x-pack/certutil csr --silent --in instances.yml --out test2.zip --pass testpassword bin/elasticsearch-certutil csr --silent --in instances.yml --out test2.zip --pass testpassword
-------------------------------------------------- --------------------------------------------------
This command generates a compressed file, which contains a directory for each This command generates a compressed file, which contains a directory for each

View File

@ -439,7 +439,7 @@ or separate keys used for each of those.
The Elastic Stack uses X.509 certificates with RSA private keys for SAML The Elastic Stack uses X.509 certificates with RSA private keys for SAML
cryptography. These keys can be generated using any standard SSL tool, including cryptography. These keys can be generated using any standard SSL tool, including
the `certutil` tool that ships with X-Pack. the `elasticsearch-certutil` tool that ships with X-Pack.
Your IdP may require that the Elastic Stack have a cryptographic key for signing Your IdP may require that the Elastic Stack have a cryptographic key for signing
SAML messages, and that you provide the corresponding signing certificate within SAML messages, and that you provide the corresponding signing certificate within
@ -462,12 +462,12 @@ You should consult the documentation for your IdP to determine what formats they
support. Since PEM format is the most commonly supported format, the examples support. Since PEM format is the most commonly supported format, the examples
below will generate certificates in that format. below will generate certificates in that format.
Using the {ref}/certutil.html[`certutil`] tool, you can generate a signing Using the {ref}/certutil.html[`elasticsearch-certutil`] tool, you can generate a
certificate with the following command: signing certificate with the following command:
[source, sh] [source, sh]
-------------------------------------------------- --------------------------------------------------
bin/x-pack/certutil cert -pem -days 1100 -name saml-sign -out saml-sign.zip bin/elasticsearch-certutil cert -pem -days 1100 -name saml-sign -out saml-sign.zip
-------------------------------------------------- --------------------------------------------------
This will This will

View File

@ -13,21 +13,22 @@ names (SAN) that correspond to the node's IP address and DNS name so that
hostname verification can be performed. hostname verification can be performed.
In order to simplify the process of generating certificates for the Elastic In order to simplify the process of generating certificates for the Elastic
Stack, a command line tool, {ref}/certutil.html[`certutil`] has been included Stack, a command line tool, {ref}/certutil.html[`elasticsearch-certutil`] has been
with {xpack}. This tool takes care of generating a CA and signing certificates included with {xpack}. This tool takes care of generating a CA and signing
with the CA. `certutil` can be used interactively or in a silent mode through certificates with the CA. `elasticsearch-certutil` can be used interactively or
the use of an input file. The `certutil` tool also supports generation of in a silent mode through the use of an input file. The `elasticsearch-certutil`
certificate signing requests (CSR), so that a commercial- or tool also supports generation of certificate signing requests (CSR), so that a
organization-specific CA can be used to sign the certificates. For example: commercial- or organization-specific CA can be used to sign the certificates.
For example:
. Optional: Create a certificate authority for your {es} cluster. . Optional: Create a certificate authority for your {es} cluster.
+ +
-- --
For example, use the `certutil ca` command: For example, use the `elasticsearch-certutil ca` command:
[source,shell] [source,shell]
---------------------------------------------------------- ----------------------------------------------------------
bin/x-pack/certutil ca bin/elasticsearch-certutil ca
---------------------------------------------------------- ----------------------------------------------------------
You can configure the cluster to trust all nodes that have a certificate that You can configure the cluster to trust all nodes that have a certificate that
@ -37,19 +38,19 @@ The command outputs a single file, with a default name of `elastic-stack-ca.p12`
This file is a PKCS#12 keystore that contains the public certificate for your CA This file is a PKCS#12 keystore that contains the public certificate for your CA
and the private key that is used to sign the certificates for each node. and the private key that is used to sign the certificates for each node.
The `certutil` command also prompts you for a password to protect the file and The `elasticsearch-certutil` command also prompts you for a password to protect
key. If you plan to add more nodes to your cluster in the future, retain a copy the file and key. If you plan to add more nodes to your cluster in the future,
of the file and remember its password. retain a copy of the file and remember its password.
-- --
. Generate a certificate and private key for for each node in your cluster. . Generate a certificate and private key for for each node in your cluster.
+ +
-- --
For example, use the `certutil cert` command: For example, use the `elasticsearch-certutil cert` command:
[source,shell] [source,shell]
---------------------------------------------------------- ----------------------------------------------------------
bin/x-pack/certutil cert --ca elastic-stack-ca.p12 bin/elasticsearch-certutil cert --ca elastic-stack-ca.p12
---------------------------------------------------------- ----------------------------------------------------------
The output is a single PKCS#12 keystore that includes the node certificate, node The output is a single PKCS#12 keystore that includes the node certificate, node
key, and CA certificate. key, and CA certificate.
@ -57,21 +58,23 @@ key, and CA certificate.
You are also prompted for a password. You can enter a password for your You are also prompted for a password. You can enter a password for your
certificate and key, or you can leave the password blank by pressing Enter. certificate and key, or you can leave the password blank by pressing Enter.
By default `certutil` generates certificates that have no hostname information By default `elasticsearch-certutil` generates certificates that have no hostname
in them (that is, they do not have any Subject Alternative Name fields). information in them (that is, they do not have any Subject Alternative Name
This means that you can use the certificate for every node in your cluster, but fields). This means that you can use the certificate for every node in your
you must turn off hostname verification as shown in the configuration below. cluster, but you must turn off hostname verification as shown in the
configuration below.
If you want to use hostname verification within your cluster, run the If you want to use hostname verification within your cluster, run the
`certutil cert` command once for each of your nodes and provide the `--name`, `elasticsearch-certutil cert` command once for each of your nodes and provide
`--dns` and `--ip` options. the `--name`, `--dns` and `--ip` options.
NOTE: You should secure the output files, since they contain the private keys NOTE: You should secure the output files, since they contain the private keys
for your instance. for your instance.
Alternatively, if you want to use a commercial or organization-specific CA, Alternatively, if you want to use a commercial or organization-specific CA,
you can use the `certutil csr` command to generate certificate signing requests you can use the `elasticsearch-certutil csr` command to generate certificate
(CSR) for the nodes in your cluster. For more information, see <<certutil>>. signing requests (CSR) for the nodes in your cluster. For more information, see
<<certutil>>.
-- --
. Copy the node certificate to the appropriate locations. . Copy the node certificate to the appropriate locations.
@ -85,8 +88,9 @@ For each additional Elastic product that you want to configure, copy the
certificates to the relevant configuration directory. certificates to the relevant configuration directory.
-- --
NOTE: If you choose not to use `certutil`, the certificates that you obtain must NOTE: If you choose not to use `elasticsearch-certutil`, the certificates that
allow for both `clientAuth` and `serverAuth` if the extended key usage extension you obtain must allow for both `clientAuth` and `serverAuth` if the extended key
is present. The certificates need to be in PEM or PKCS#12 format. Although not usage extension is present. The certificates need to be in PEM or PKCS#12
required, it is highly recommended that the certificate contain the DNS names format. Although not required, it is highly recommended that the certificate
and/or IP addresses of the node so that hostname verification can be used. contain the DNS names and/or IP addresses of the node so that hostname
verification can be used.

View File

@ -28,9 +28,9 @@ xpack.security.http.ssl.truststore.path: certs/elastic-certificates.p12 <2>
<1> If you created a separate certificate for each node, then you might need to <1> If you created a separate certificate for each node, then you might need to
customize this path on each node. If the filename matches the node name, you can customize this path on each node. If the filename matches the node name, you can
use the `certs/${node.name}.p12` format, for example. use the `certs/${node.name}.p12` format, for example.
<2> The `certutil` output includes the CA certificate inside the PKCS#12 <2> The `elasticsearch-certutil` output includes the CA certificate inside the
keystore, therefore the keystore can also be used as the truststore. This name PKCS#12 keystore, therefore the keystore can also be used as the truststore.
should match the `keystore.path` value. This name should match the `keystore.path` value.
-- --
** If the certificate is in PEM format, add the following information to the ** If the certificate is in PEM format, add the following information to the

View File

@ -22,7 +22,7 @@ xpack.security.transport.ssl.verification_mode: certificate <1>
xpack.security.transport.ssl.keystore.path: certs/elastic-certificates.p12 <2> xpack.security.transport.ssl.keystore.path: certs/elastic-certificates.p12 <2>
xpack.security.transport.ssl.truststore.path: certs/elastic-certificates.p12 <3> xpack.security.transport.ssl.truststore.path: certs/elastic-certificates.p12 <3>
----------------------------------------------------------- -----------------------------------------------------------
<1> If you used the `--dns` or `--ip` options with the `certutil cert` command <1> If you used the `--dns` or `--ip` options with the `elasticsearch-certutil cert` command
and you want to enable strict hostname checking, set the verification mode to and you want to enable strict hostname checking, set the verification mode to
`full`. `full`.
See <<ssl-tls-settings, `xpack.ssl.verification_mode`>> for a description of these values. See <<ssl-tls-settings, `xpack.ssl.verification_mode`>> for a description of these values.
@ -30,9 +30,9 @@ See <<ssl-tls-settings, `xpack.ssl.verification_mode`>> for a description of the
<2> If you created a separate certificate for each node, then you might need to <2> If you created a separate certificate for each node, then you might need to
customize this path on each node. If the filename matches the node name, you can customize this path on each node. If the filename matches the node name, you can
use the `certs/${node.name}.p12` format, for example. use the `certs/${node.name}.p12` format, for example.
<3> The `certutil` output includes the CA certificate inside the PKCS#12 <3> The `elasticsearch-certutil` output includes the CA certificate inside the
keystore, therefore the keystore can also be used as the truststore. This name PKCS#12 keystore, therefore the keystore can also be used as the truststore.
should match the `keystore.path` value. This name should match the `keystore.path` value.
-- --
** If the certificate is in PEM format, add the following information to the ** If the certificate is in PEM format, add the following information to the
@ -47,7 +47,7 @@ xpack.security.transport.ssl.key: /home/es/config/x-pack/node01.key <2>
xpack.security.transport.ssl.certificate: /home/es/config/x-pack/node01.crt <3> xpack.security.transport.ssl.certificate: /home/es/config/x-pack/node01.crt <3>
xpack.security.transport.ssl.certificate_authorities: [ "/home/es/config/x-pack/ca.crt" ] <4> xpack.security.transport.ssl.certificate_authorities: [ "/home/es/config/x-pack/ca.crt" ] <4>
-------------------------------------------------- --------------------------------------------------
<1> If you used the `--dns` or `--ip` options with the `certutil cert` command <1> If you used the `--dns` or `--ip` options with the `elasticsearch-certutil cert` command
and you want to enable strict hostname checking, set the verification mode to and you want to enable strict hostname checking, set the verification mode to
`full`. `full`.
See <<ssl-tls-settings, `xpack.ssl.verification_mode`>> for a description of these values. See <<ssl-tls-settings, `xpack.ssl.verification_mode`>> for a description of these values.

View File

@ -500,7 +500,8 @@ public class CertificateGenerateTool extends EnvironmentAwareCommand {
private static void printIntro(Terminal terminal, boolean csr) { private static void printIntro(Terminal terminal, boolean csr) {
terminal.println("******************************************************************************"); terminal.println("******************************************************************************");
terminal.println("Note: The 'elasticsearch-certgen' tool has been deprecated in favour of the"); terminal.println("Note: The 'elasticsearch-certgen' tool has been deprecated in favour of the");
terminal.println(" 'certutil' tool. This command will be removed in a future release."); terminal.println(" 'elasticsearch-certutil' tool. This command will be removed in a future");
terminal.println(" release.");
terminal.println("******************************************************************************"); terminal.println("******************************************************************************");
terminal.println(""); terminal.println("");

View File

@ -16,8 +16,8 @@ verify_xpack_installation() {
local binaryFiles=( local binaryFiles=(
'elasticsearch-certgen' 'elasticsearch-certgen'
'elasticsearch-certgen.bat' 'elasticsearch-certgen.bat'
'certutil' 'elasticsearch-certutil'
'certutil.bat' 'elasticsearch-certutil.bat'
'croneval' 'croneval'
'croneval.bat' 'croneval.bat'
'migrate' 'migrate'

View File

@ -4,7 +4,7 @@ idp-ca.crt
idp-ca.key idp-ca.key
Description: A CA for the IdP Description: A CA for the IdP
Generated Date: 2018-02-07 Generated Date: 2018-02-07
Command: bin/x-pack/certutil ca --ca-dn 'CN=idp-fixture,OU=elasticsearch,DC=elastic,DC=co' --days 5000 -keysize 1024 --out idp-ca.zip --pem Command: bin/elasticsearch-certutil ca --ca-dn 'CN=idp-fixture,OU=elasticsearch,DC=elastic,DC=co' --days 5000 -keysize 1024 --out idp-ca.zip --pem
X-Pack Version: 6.2.0 X-Pack Version: 6.2.0
idptrust.jks idptrust.jks