From dc3d5d67a1e1096ff2693bd503e5d6c96ac314f6 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Mon, 8 Jan 2018 10:14:51 -0800 Subject: [PATCH] [DOCS] Change certgen references to certutil (elastic/x-pack-elasticsearch#3415) * [DOCS] Change certgen references to certutil * [DOCS] Updated TLS page with certutil info * [DOCS] Added certutil examples to TLS page * [DOCS] Clarified PEM requirement in TLS setup * [DOCS] Updated certificate instructions * [DOCS] Fixed security typo Original commit: elastic/x-pack-elasticsearch@3a326fc87d5a7b2cfe9a30dd4278514ae8113f39 --- .../setting-up-ssl.asciidoc | 37 ++++-- docs/en/setup/installing-xes.asciidoc | 108 +++++++++++++----- 2 files changed, 107 insertions(+), 38 deletions(-) diff --git a/docs/en/security/securing-communications/setting-up-ssl.asciidoc b/docs/en/security/securing-communications/setting-up-ssl.asciidoc index e10cf84e15b..048847b03ff 100644 --- a/docs/en/security/securing-communications/setting-up-ssl.asciidoc +++ b/docs/en/security/securing-communications/setting-up-ssl.asciidoc @@ -20,7 +20,7 @@ the cluster: . Restart Elasticsearch. [[installing-node-certificates]] -==== Node Certificates +==== Generating Node Certificates TLS requires X.509 certificates to perform encryption and authentication of the application that is being communicated with. In order for the communication between nodes to be truly @@ -29,20 +29,37 @@ certificate authenticity in a Elasticsearch cluster is to trust the certificate that signed the certificate. By doing this, as nodes are added to your cluster they just need to use a certificate signed by the same CA and the node is automatically allowed to join the cluster. Additionally, it is recommended that the certificates contain subject alternative -names (SAN) that correspond to the node's ip address and dns name so that hostname verification +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, `certgen` has been included with {xpack}. This tool takes care of the generating -a CA and signing certificates with the CA. `certgen` can be used interactively or in a silent -mode through the use of an input file. The `certgen` tool also supports generation of certificate -signing requests (CSR), so that a commercial or organization specific CA may be used to sign -the certificates. For more information, see {ref}/certgen.html[certgen]. +line tool, {ref}/certutil.html[`certutil`] has been included with {xpack}. This +tool takes care of the 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: -NOTE: If you choose not to use `certgen`, the certificates that you obtain must allow for both +1. Optional: Create a certificate authority by using the `certutil ca` command. +2. Generate a certificate for each node by using the `certutil cert` command. ++ +-- +NOTE: You should secure the output files, since they contain the private keys +for your instance. + +-- +3. Copy the node certificate to the appropriate locations. For each Elastic +product that you want to configure, copy the certificates to the relevant +configuration directory. For more information, see +<>, +{kibana-ref}/using-kibana-with-security.html[Configuring security in {kib}], and +{logstash-ref}/ls-security.html[Configuring security in Logstash]. + +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 format. Although not required, it is highly recommended that the certificate contain -the dns name(s) and/or ip address(es) of the node so that hostname verification may be used. +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. + [[enable-ssl]] ==== Enabling SSL in the Node Configuration diff --git a/docs/en/setup/installing-xes.asciidoc b/docs/en/setup/installing-xes.asciidoc index 0175137c5d4..8932be4f17e 100644 --- a/docs/en/setup/installing-xes.asciidoc +++ b/docs/en/setup/installing-xes.asciidoc @@ -146,11 +146,12 @@ the correct value for your environment, you may consider setting the value to `*` which will allow automatic creation of all indices. ============================================================================= -. Configure passwords and SSL/TLS. -.. If you have a non-trial license and you want to use {security}, you must -configure SSL/TLS for internode-communication. +. Configure Transport Layer Security (TLS/SSL). + -- +If you have a non-trial license and you want to use {security}, you must +configure TLS for internode-communication. + NOTE: This requirement applies to clusters with more than one node and to clusters with a single node that listens on an external interface. Single-node clusters that use a loopback interface do not have this requirement. For more @@ -158,46 +159,97 @@ information, see {xpack-ref}/encrypting-communications.html[Encrypting Communications]. -- -... Generate node certificates. For example, you can use the `certgen` command -line tool to generate a certificate authority and signed certificates for your -nodes. +.. Generate node certificates. For example, you can use the `certutil` command +line tool to generate a certificate authority (CA) and signed certificates for +your nodes. For more information, see <>. + +... Generate a new Certificate Authority (CA) for your {es} cluster: + -- [source,shell] ---------------------------------------------------------- -bin/x-pack/certgen +bin/x-pack/certutil ca ---------------------------------------------------------- -This command generates a zip file with the CA certificate, private key, and -signed certificates and keys in the PEM format for each node that you specify. -If you want to use a commercial or organization-specific CA, you can use the -`-csr` parameter to generate certificate signing requests (CSR) for the nodes -in your cluster. For more information, see <>. -TIP: For easier setup, use the node name as the instance name when you run -this tool. +You can configure the cluster to trust all nodes that have a certificate that +has been signed by this CA. +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. -- -... Copy the certificate data into a directory within the {es} configuration -directory. For example, -`/home/es/config/certs`. -... Add the following information to the `elasticsearch.yml` on all nodes: + +... Generate a certificate and private key for each node in your cluster: ++ +-- +[source,shell] +---------------------------------------------------------- +bin/x-pack/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. + +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. + +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. +-- +... 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 <>. + +.. Copy the applicable `.p12` file into a directory within the {es} configuration +directory on each node. For example, `/home/es/config/certs`. There is no need +to copy the CA file to this directory. + +.. Add the following information to the `elasticsearch.yml` file on each node: + -- [source,yaml] ----------------------------------------------------------- -xpack.ssl.key: certs/${node.name}/${node.name}.key <1> -xpack.ssl.certificate: certs/${node.name}/${node.name}.crt <2> -xpack.ssl.certificate_authorities: certs/ca/ca.crt <3> +xpack.ssl.keystore.path: certs/elastic-certificates.p12 <1> +xpack.ssl.truststore.path: certs/elastic-certificates.p12 <2> +xpack.security.transport.ssl.verification_mode: certificate <3> xpack.security.transport.ssl.enabled: true ----------------------------------------------------------- -<1> If this path does not exist on every node or the file name does not match -the `node.name` configuration setting, you must specify the full path to the -node key file. -<2> Alternatively, specify the full path to the node certificate. -<3> Alternatively specify the full path to the CA certificate. +<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. +<3> If you used the `--dns` or `--ip` options with the `certutil cert` command +and you want to enable strict hostname checking, set the verification mode to +`full`. + +For more information about these settings, see +{ref}/security-settings.html[Security Settings in {es}]. -- -.. Start {es}. +.. If you secured the node's PKCS#12 file with a password, then you must add +the password to your {es} keystore. Run the following commands: ++ +-- +[source,shell] +----------------------------------------------------------- +bin/elasticsearch-keystore add xpack.ssl.keystore.secure_password + +bin/elasticsearch-keystore add xpack.ssl.truststore.secure_password +----------------------------------------------------------- +-- + +. Start {es}. + -- [source,shell] @@ -206,7 +258,7 @@ bin/elasticsearch ---------------------------------------------------------- -- -.. Set the passwords for all built-in users. The +setup-passwords+ command is +. Set the passwords for all built-in users. The +setup-passwords+ command is the simplest method to set the built-in users' passwords for the first time. + --