From 03ffd1692124f42a6a21860534d07c22bc5cef88 Mon Sep 17 00:00:00 2001 From: Jason Tedor Date: Tue, 10 Apr 2018 18:57:08 -0400 Subject: [PATCH] Rename certutil This commit renames certutil to elasticsearch-certutil. --- x-pack/docs/en/commands/certutil.asciidoc | 30 +++++----- .../authentication/saml-guide.asciidoc | 8 +-- .../node-certificates.asciidoc | 56 ++++++++++--------- .../securing-communications/tls-http.asciidoc | 6 +- .../tls-transport.asciidoc | 10 ++-- .../core/ssl/CertificateGenerateTool.java | 3 +- .../bin/{certutil => elasticsearch-certutil} | 0 ...ertutil.bat => elasticsearch-certutil.bat} | 0 .../test/resources/packaging/utils/xpack.bash | 4 +- .../src/main/resources/certs/README.txt | 2 +- 10 files changed, 62 insertions(+), 57 deletions(-) rename x-pack/plugin/security/src/main/bin/{certutil => elasticsearch-certutil} (100%) rename x-pack/plugin/security/src/main/bin/{certutil.bat => elasticsearch-certutil.bat} (100%) diff --git a/x-pack/docs/en/commands/certutil.asciidoc b/x-pack/docs/en/commands/certutil.asciidoc index abb85df17cc..ad265c89f10 100644 --- a/x-pack/docs/en/commands/certutil.asciidoc +++ b/x-pack/docs/en/commands/certutil.asciidoc @@ -1,16 +1,16 @@ [role="xpack"] [[certutil]] -== certutil +== elasticsearch-certutil -The `certutil` command simplifies the creation of certificates for use with -Transport Layer Security (TLS) in the Elastic Stack. +The `elasticsearch-certutil` command simplifies the creation of certificates for +use with Transport Layer Security (TLS) in the Elastic Stack. [float] === Synopsis [source,shell] -------------------------------------------------- -bin/x-pack/certutil +bin/elasticsearch-certutil ( (ca [--ca-dn ] [--days ] [--pem]) @@ -31,9 +31,9 @@ bin/x-pack/certutil [float] === Description -You can specify one of the following modes: `ca`, `cert`, `csr`. The `certutil` -command also supports a silent mode of operation to enable easier batch -operations. +You can specify one of the following modes: `ca`, `cert`, `csr`. The +`elasticsearch-certutil` command also supports a silent mode of operation to +enable easier batch operations. [float] [[certutil-ca]] @@ -199,7 +199,7 @@ format: [source, sh] -------------------------------------------------- -bin/x-pack/certutil ca +bin/elasticsearch-certutil ca -------------------------------------------------- You are prompted for an output filename and a password. Alternatively, you can @@ -210,7 +210,7 @@ CA. For example: [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. @@ -223,7 +223,7 @@ product that you want to configure. For more information, see [float] [[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 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 valid filename, then the `filename` field must be present. -When your YAML file is ready, you can use the `certutil` command to generate -certificates or certificate signing requests. Simply use the `--in` parameter to -specify the location of the file. For example: +When your YAML file is ready, you can use the `elasticsearch-certutil` command +to generate certificates or certificate signing requests. Simply use the `--in` +parameter to specify the location of the file. For example: [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 @@ -281,7 +281,7 @@ example: [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 diff --git a/x-pack/docs/en/security/authentication/saml-guide.asciidoc b/x-pack/docs/en/security/authentication/saml-guide.asciidoc index f09fc41c23f..4ce09781d51 100644 --- a/x-pack/docs/en/security/authentication/saml-guide.asciidoc +++ b/x-pack/docs/en/security/authentication/saml-guide.asciidoc @@ -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 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 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 below will generate certificates in that format. -Using the {ref}/certutil.html[`certutil`] tool, you can generate a signing -certificate with the following command: +Using the {ref}/certutil.html[`elasticsearch-certutil`] tool, you can generate a +signing certificate with the following command: [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 diff --git a/x-pack/docs/en/security/securing-communications/node-certificates.asciidoc b/x-pack/docs/en/security/securing-communications/node-certificates.asciidoc index a621d6ecfba..604355e21bf 100644 --- a/x-pack/docs/en/security/securing-communications/node-certificates.asciidoc +++ b/x-pack/docs/en/security/securing-communications/node-certificates.asciidoc @@ -13,21 +13,22 @@ names (SAN) that correspond to the node's IP address and DNS name so that hostname verification can be performed. In order to simplify the process of generating certificates for the Elastic -Stack, a command line tool, {ref}/certutil.html[`certutil`] has been included -with {xpack}. This tool takes care of generating a CA and signing certificates -with the CA. `certutil` can be used interactively or in a silent mode through -the use of an input file. The `certutil` tool also supports generation of -certificate signing requests (CSR), so that a commercial- or -organization-specific CA can be used to sign the certificates. For example: +Stack, a command line tool, {ref}/certutil.html[`elasticsearch-certutil`] has been +included with {xpack}. This tool takes care of generating a CA and signing +certificates with the CA. `elasticsearch-certutil` can be used interactively or +in a silent mode through the use of an input file. The `elasticsearch-certutil` +tool also supports generation of certificate signing requests (CSR), so that a +commercial- or organization-specific CA can be used to sign the certificates. +For example: . 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] ---------------------------------------------------------- -bin/x-pack/certutil ca +bin/elasticsearch-certutil ca ---------------------------------------------------------- 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 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 -key. If you plan to add more nodes to your cluster in the future, retain a copy -of the file and remember its password. +The `elasticsearch-certutil` command also prompts you for a password to protect +the file and key. If you plan to add more nodes to your cluster in the future, +retain a copy of the file and remember its password. -- . 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] ---------------------------------------------------------- -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 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 certificate and key, or you can leave the password blank by pressing Enter. -By default `certutil` generates certificates that have no hostname information -in them (that is, they do not have any Subject Alternative Name fields). -This means that you can use the certificate for every node in your cluster, but -you must turn off hostname verification as shown in the configuration below. +By default `elasticsearch-certutil` generates certificates that have no hostname +information in them (that is, they do not have any Subject Alternative Name +fields). This means that you can use the certificate for every node in your +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 -`certutil cert` command once for each of your nodes and provide the `--name`, -`--dns` and `--ip` options. +`elasticsearch-certutil cert` command once for each of your nodes and provide +the `--name`, `--dns` and `--ip` options. NOTE: You should secure the output files, since they contain the private keys for your instance. Alternatively, if you want to use a commercial or organization-specific CA, -you can use the `certutil csr` command to generate certificate signing requests -(CSR) for the nodes in your cluster. For more information, see <>. +you can use the `elasticsearch-certutil csr` command to generate certificate +signing requests (CSR) for the nodes in your cluster. For more information, see +<>. -- . 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. -- -NOTE: If you choose not to use `certutil`, the certificates that you obtain must -allow for both `clientAuth` and `serverAuth` if the extended key usage extension -is present. The certificates need to be in PEM or PKCS#12 format. Although not -required, it is highly recommended that the certificate contain the DNS names -and/or IP addresses of the node so that hostname verification can be used. +NOTE: If you choose not to use `elasticsearch-certutil`, the certificates that +you obtain must allow for both `clientAuth` and `serverAuth` if the extended key +usage extension is present. The certificates need to be in PEM or PKCS#12 +format. Although not required, it is highly recommended that the certificate +contain the DNS names and/or IP addresses of the node so that hostname +verification can be used. diff --git a/x-pack/docs/en/security/securing-communications/tls-http.asciidoc b/x-pack/docs/en/security/securing-communications/tls-http.asciidoc index e6b1481483d..dae088667c6 100644 --- a/x-pack/docs/en/security/securing-communications/tls-http.asciidoc +++ b/x-pack/docs/en/security/securing-communications/tls-http.asciidoc @@ -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 customize this path on each node. If the filename matches the node name, you can use the `certs/${node.name}.p12` format, for example. -<2> The `certutil` output includes the CA certificate inside the PKCS#12 -keystore, therefore the keystore can also be used as the truststore. This name -should match the `keystore.path` value. +<2> The `elasticsearch-certutil` output includes the CA certificate inside the +PKCS#12 keystore, therefore the keystore can also be used as the truststore. +This name should match the `keystore.path` value. -- ** If the certificate is in PEM format, add the following information to the diff --git a/x-pack/docs/en/security/securing-communications/tls-transport.asciidoc b/x-pack/docs/en/security/securing-communications/tls-transport.asciidoc index bd0bb74dfcb..9bce211a1e2 100644 --- a/x-pack/docs/en/security/securing-communications/tls-transport.asciidoc +++ b/x-pack/docs/en/security/securing-communications/tls-transport.asciidoc @@ -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.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 `full`. See <> for a description of these values. @@ -30,9 +30,9 @@ See <> for a description of the <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 use the `certs/${node.name}.p12` format, for example. -<3> The `certutil` output includes the CA certificate inside the PKCS#12 -keystore, therefore the keystore can also be used as the truststore. This name -should match the `keystore.path` value. +<3> The `elasticsearch-certutil` output includes the CA certificate inside the +PKCS#12 keystore, therefore the keystore can also be used as the truststore. +This name should match the `keystore.path` value. -- ** 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_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 `full`. See <> for a description of these values. diff --git a/x-pack/plugin/core/src/main/java/org/elasticsearch/xpack/core/ssl/CertificateGenerateTool.java b/x-pack/plugin/core/src/main/java/org/elasticsearch/xpack/core/ssl/CertificateGenerateTool.java index b79a7117966..eb3a92ce5e8 100644 --- a/x-pack/plugin/core/src/main/java/org/elasticsearch/xpack/core/ssl/CertificateGenerateTool.java +++ b/x-pack/plugin/core/src/main/java/org/elasticsearch/xpack/core/ssl/CertificateGenerateTool.java @@ -500,7 +500,8 @@ public class CertificateGenerateTool extends EnvironmentAwareCommand { private static void printIntro(Terminal terminal, boolean csr) { terminal.println("******************************************************************************"); 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(""); diff --git a/x-pack/plugin/security/src/main/bin/certutil b/x-pack/plugin/security/src/main/bin/elasticsearch-certutil similarity index 100% rename from x-pack/plugin/security/src/main/bin/certutil rename to x-pack/plugin/security/src/main/bin/elasticsearch-certutil diff --git a/x-pack/plugin/security/src/main/bin/certutil.bat b/x-pack/plugin/security/src/main/bin/elasticsearch-certutil.bat similarity index 100% rename from x-pack/plugin/security/src/main/bin/certutil.bat rename to x-pack/plugin/security/src/main/bin/elasticsearch-certutil.bat diff --git a/x-pack/qa/vagrant/src/test/resources/packaging/utils/xpack.bash b/x-pack/qa/vagrant/src/test/resources/packaging/utils/xpack.bash index e2172156d8e..1cdd3bf7abe 100644 --- a/x-pack/qa/vagrant/src/test/resources/packaging/utils/xpack.bash +++ b/x-pack/qa/vagrant/src/test/resources/packaging/utils/xpack.bash @@ -16,8 +16,8 @@ verify_xpack_installation() { local binaryFiles=( 'elasticsearch-certgen' 'elasticsearch-certgen.bat' - 'certutil' - 'certutil.bat' + 'elasticsearch-certutil' + 'elasticsearch-certutil.bat' 'croneval' 'croneval.bat' 'migrate' diff --git a/x-pack/test/idp-fixture/src/main/resources/certs/README.txt b/x-pack/test/idp-fixture/src/main/resources/certs/README.txt index 3259198fd3a..0cf738156a7 100644 --- a/x-pack/test/idp-fixture/src/main/resources/certs/README.txt +++ b/x-pack/test/idp-fixture/src/main/resources/certs/README.txt @@ -4,7 +4,7 @@ idp-ca.crt idp-ca.key Description: A CA for the IdP 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 idptrust.jks