diff --git a/docs/en/commands/certgen.asciidoc b/docs/en/commands/certgen.asciidoc index f0aabee30f8..7b93ecdc090 100644 --- a/docs/en/commands/certgen.asciidoc +++ b/docs/en/commands/certgen.asciidoc @@ -2,6 +2,8 @@ [[certgen]] == certgen +deprecated[6.1,Replaced by <>. ] + The `certgen` command simplifies the creation of certificate authorities (CA), certificate signing requests (CSR), and signed certificates for use with the Elastic Stack. @@ -56,7 +58,7 @@ signed certificates must be in PEM format to work with {security}. using an existing CA certificate, which is provided in the `` argument. This parameter cannot be used with the `-csr` parameter. -`--csr`:: Specifies to operation in certificate signing request mode. +`--csr`:: Specifies to operate in certificate signing request mode. `--days `:: Specifies an integer value that represents the number of days the generated keys diff --git a/docs/en/commands/certutil.asciidoc b/docs/en/commands/certutil.asciidoc new file mode 100644 index 00000000000..605d4a2d9fe --- /dev/null +++ b/docs/en/commands/certutil.asciidoc @@ -0,0 +1,279 @@ +[role="xpack"] +[[certutil]] +== certutil + +The `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 +( +(ca [--ca-dn ] [--days ] [--pem]) + +| (cert ([--ca ] | [--ca-cert --ca-key ]) +[--ca-dn ] [--ca-pass ] [--days ] +[--dns ] [--in ] [--ip ] +[--keep-ca-key] [--multiple] [--name ] [--pem]) + +| (csr [--dns ] [--in ] [--ip ] +[--name ]) + +[-E ] [--keysize ] [--out ] +[--pass ] +) +[-h, --help] ([-s, --silent] | [-v, --verbose]) +-------------------------------------------------- + +[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. + +[float] +[[certutil-ca]] +==== CA mode + +The `ca` mode generates a new certificate authority (CA). By default, it +produces a single PKCS#12 output file, which holds the CA certificate and the +private key for the CA. If you specify the `--pem` parameter, the command +generates a zip file, which contains the certificate and private key in PEM +format. + +You can subsequently use these files as input for the `cert` mode of the command. + +[float] +[[certutil-cert]] +==== CERT mode + +The `cert` mode generates X.509 certificates and private keys. By default, it +produces a single certificate and key for use on a single instance. + +To generate certificates and keys for multiple instances, specify the +`--multiple` parameter, which prompts you for details about each instance. +Alternatively, you can use the `--in` parameter to specify a YAML file that +contains details about the instances. + +An instance is any piece of the Elastic Stack that requires a TLS or SSL +certificate. Depending on your configuration, {es}, Logstash, {kib}, and Beats +might all require a certificate and private key. The minimum required +information for an instance is its name, which is used as the common name for +the certificate. The instance name can be a hostname value or a full +distinguished name. If the instance name would result in an invalid file or +directory name, you must also specify a file name in the `--name` command +parameter or in the `filename` field in an input YAML file. + +You can optionally provide IP addresses or DNS names for each instance. If +neither IP addresses nor DNS names are specified, the Elastic stack products +cannot perform hostname verification and you might need to configure the +`verfication_mode` security setting to `certificate` only. For more information +about this setting, see <>. + +All certificates that are generated by this command are signed by a CA. You can +provide your own CA with the `--ca` or `--ca-cert` parameters. Otherwise, the +command automatically generates a new CA for you. For more information about +generating a CA, see the <>. + +By default, the `cert` mode produces a single PKCS#12 output file which holds +the instance certificate, the instance private key, and the CA certificate. If +you specify the `--pem` parameter, the command generates PEM formatted +certificates and keys and packages them into a zip file. Likewise if you chose +to generate output for multiple instances, the command produces a zip file. + +[float] +[[certutil-csr]] +==== CSR mode + +The `csr` mode generates certificate signing requests (CSRs) that you can send +to a trusted certificate authority to obtain signed certificates. The signed +certificates must be in PEM or PKCS#12 format to work with {security}. + +By default, the command produces a single CSR for a single instance. + +To generate CSRs for multiple instances, specify the `--multiple` parameter, +which prompts you for details about each instance. Alternatively, you can use +the `--in` parameter to specify a YAML file that contains details about the +instances. + +The `cert` mode produces a single zip file which contains the CSRs and the +private keys for each instance. Each CSR is provided as a standard PEM +encoding of a PKCS#10 CSR. Each key is provided as a PEM encoding of an RSA +private key. + +[float] +=== Parameters + +`ca`:: Specifies to generate a new local certificate authority (CA). This +parameter cannot be used with the `csr` or `cert` parameters. + +`cert`:: Specifies to generate new X.509 certificates and keys. +This parameter cannot be used with the `csr` or `ca` parameters. + +`csr`:: Specifies to generate certificate signing requests. This parameter +cannot be used with the `ca` or `cert` parameters. + +`--ca `:: Specifies the path to an existing CA key pair +(in PKCS#12 format). This parameter cannot be used with the `ca` or `csr` parameters. + +`--ca-cert `:: Specifies the path to an existing CA certificate (in +PEM format). You must also specify the `--ca-key` parameter. The `--ca-cert` +parameter cannot be used with the `ca` or `csr` parameters. + +`--ca-dn `:: Defines the _Distinguished Name_ (DN) that is used for the +generated CA certificate. The default value is +`CN=Elastic Certificate Tool Autogenerated CA`. This parameter cannot be used +with the `csr` parameter. + +`--ca-key `:: Specifies the path to an existing CA private key (in +PEM format). You must also specify the `--ca-cert` parameter. The `--ca-key` +parameter cannot be used with the `ca` or `csr` parameters. + +`--ca-pass `:: Specifies the password for an existing CA private key +or the generated CA private key. This parameter cannot be used with the `ca` or +`csr` parameters. + +`--days `:: Specifies an integer value that represents the number of days the +generated certificates are valid. The default value is `1095`. This parameter +cannot be used with the `csr` parameter. + +`--dns `:: Specifies a comma-separated list of DNS names. This +parameter cannot be used with the `ca` parameter. + +`-E `:: Configures a setting. + +`-h, --help`:: Returns all of the command parameters. + +`--in `:: Specifies the file that is used to run in silent mode. The +input file must be a YAML file. This parameter cannot be used with the `ca` +parameter. + +`--ip `:: Specifies a comma-separated list of IP addresses. This +parameter cannot be used with the `ca` parameter. + +`--keep-ca-key`:: When running in `cert` mode with an automatically-generated +CA, specifies to retain the CA private key for future use. + +`--keysize `:: +Defines the number of bits that are used in generated RSA keys. The default +value is `2048`. + +`--multiple`:: +Specifies to generate files for multiple instances. This parameter cannot be +used with the `ca` parameter. + +`--name `:: +Specifies the name of the generated certificate. This parameter cannot be used +with the `ca` parameter. + +`--out `:: Specifies a path for the output files. + +`--pass `:: Specifies the password for the generated private keys. + +`--pem`:: Generates certificates and keys in PEM format instead of PKCS#12. This +parameter cannot be used with the `csr` parameter. + +`-s, --silent`:: Shows minimal output. + +`-v, --verbose`:: Shows verbose output. + +[float] +=== Examples + +The following command generates a CA certificate and private key in PKCS#12 +format: + +[source, sh] +-------------------------------------------------- +bin/x-pack/certutil ca +-------------------------------------------------- + +You are prompted for an output filename and a password. Alternatively, you can +specify the `--out` and `--pass` parameters. + +You can then generate X.509 certificates and private keys by using the new +CA. For example: + +[source, sh] +-------------------------------------------------- +bin/x-pack/certutil cert --ca elastic-stack-ca.p12 +-------------------------------------------------- + +You are prompted for the CA password and for an output filename and password. +Alternatively, you can specify the `--ca-pass`, `--out`, and `--pass` parameters. + +By default, this command generates a file called `elastic-certificates.p12`, +which you can copy to the relevant configuration directory for each Elastic +product that you want to configure. For more information, see +{xpack-ref}/ssl-tls.html[Setting Up TLS on a Cluster]. + +[float] +[[certutil-silent]] +==== Using `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: + +[source, yaml] +-------------------------------------------------- +instances: + - name: "node1" <1> + ip: <2> + - "192.0.2.1" + dns: <3> + - "node1.mydomain.com" + - name: "node2" + ip: + - "192.0.2.2" + - "198.51.100.1" + - name: "node3" + - name: "node4" + dns: + - "node4.mydomain.com" + - "node4.internal" + - name: "CN=node5,OU=IT,DC=mydomain,DC=com" + filename: "node5" <4> +-------------------------------------------------- +<1> The name of the instance. This can be a simple string value or can be a +Distinguished Name (DN). This is the only required field. +<2> An optional array of strings that represent IP Addresses for this instance. +Both IPv4 and IPv6 values are allowed. The values are added as Subject +Alternative Names. +<3> An optional array of strings that represent DNS names for this instance. +The values are added as Subject Alternative Names. +<4> The filename to use for this instance. This name is used as the name of the +directory that contains the instance's files in the output. It is also used in +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: + +[source, sh] +-------------------------------------------------- +bin/x-pack/certutil cert --silent --in instances.yml --out test1.zip --pass testpassword +-------------------------------------------------- + +This command generates a compressed `test1.zip` file. After you decompress the +output file, there is a directory for each instance that was listed in the +`instances.yml` file. Each instance directory contains a single PKCS#12 (`.p12`) +file, which contains the instance certificate, instance private key, and CA +certificate. + +You an also use the YAML file to generate certificate signing requests. For +example: + +[source, sh] +-------------------------------------------------- +bin/x-pack/certutil csr --silent --in instances.yml --out test2.zip --pass testpassword +-------------------------------------------------- + +This command generates a compressed file, which contains a directory for each +instance. Each instance directory contains a certificate signing request +(`*.csr` file) and private key (`*.key` file). diff --git a/docs/en/commands/index.asciidoc b/docs/en/commands/index.asciidoc index 2bdc5ec6645..e839a54935f 100644 --- a/docs/en/commands/index.asciidoc +++ b/docs/en/commands/index.asciidoc @@ -8,6 +8,7 @@ {xpack} includes commands that help you configure security: * <> +* <> * <> * <> * <> @@ -16,6 +17,7 @@ -- include::certgen.asciidoc[] +include::certutil.asciidoc[] include::migrate-tool.asciidoc[] include::setup-passwords.asciidoc[] include::syskeygen.asciidoc[]