From 87e2bd710594aca50e41ada3b9c243d4e154c332 Mon Sep 17 00:00:00 2001 From: Eamonn Smith Date: Thu, 4 Mar 2021 09:39:46 +0000 Subject: [PATCH 1/4] Reorg ssl content --- libbeat/docs/shared-ssl-config.asciidoc | 437 +++++++++++++++++------- 1 file changed, 317 insertions(+), 120 deletions(-) diff --git a/libbeat/docs/shared-ssl-config.asciidoc b/libbeat/docs/shared-ssl-config.asciidoc index 31eedd1e19a..757aa3639ee 100644 --- a/libbeat/docs/shared-ssl-config.asciidoc +++ b/libbeat/docs/shared-ssl-config.asciidoc @@ -87,25 +87,154 @@ Example module with SSL enabled: ---- endif::[] -[float] -=== Configuration options +[discrete] +[[ssl-common-config]] +=== Common configuration options -You can specify the following options in the `ssl` section of the +{beatname_lc}.yml+ config file: +In the +{beatname_lc}.yml+ config file, you can specify the following common options in the +`ssl` section of each output that supports SSL. [float] +[[enabled]] ==== `enabled` -The `enabled` setting can be used to disable the ssl configuration by setting -it to `false`. The default value is `true`. +To disable the ssl configuration, set the value to `false`. The default value is `true`. -NOTE: SSL settings are disabled if either `enabled` is set to `false` or the +[NOTE] +===== +SSL settings are disabled if either `enabled` is set to `false` or the `ssl` section is missing. +===== + +[float] +[[key-passphrase]] +==== `key_passphrase` + +The passphrase used to decrypt an encrypted key stored in the configured `key` file. + +[float] +[[supported-protocols]] +==== `supported_protocols` + +List of allowed SSL/TLS versions. If SSL/TLS server decides for protocol versions +not configured, the connection will be dropped during or after the handshake. The +setting is a list of allowed protocol versions: +`SSLv3`, `TLSv1` for TLS version 1.0, `TLSv1.0`, `TLSv1.1`, `TLSv1.2`, and +`TLSv1.3`. + +The default value is `[TLSv1.1, TLSv1.2, TLSv1.3]`. + +[float] +[[cipher-suites]] +==== `cipher_suites` + +The list of cipher suites to use. The first entry has the highest priority. +If this option is omitted, the Go crypto library's https://golang.org/pkg/crypto/tls/[default suites] +are used (recommended). Note that TLS 1.3 cipher suites are not +individually configurable in Go, so they are not included in this list. + +// tag::cipher_suites[] +The following cipher suites are available: + +[options="header"] +|=== +| Cypher | Notes +| ECDHE-ECDSA-AES-128-CBC-SHA | +| ECDHE-ECDSA-AES-128-CBC-SHA256 | TLS 1.2 only. Disabled by default. +| ECDHE-ECDSA-AES-128-GCM-SHA256 | TLS 1.2 only. +| ECDHE-ECDSA-AES-256-CBC-SHA | +| ECDHE-ECDSA-AES-256-GCM-SHA384 | TLS 1.2 only. +| ECDHE-ECDSA-CHACHA20-POLY1305 | TLS 1.2 only. +| ECDHE-ECDSA-RC4-128-SHA | Disabled by default. RC4 not recommended. +| ECDHE-RSA-3DES-CBC3-SHA | +| ECDHE-RSA-AES-128-CBC-SHA | +| ECDHE-RSA-AES-128-CBC-SHA256 | TLS 1.2 only. Disabled by default. +| ECDHE-RSA-AES-128-GCM-SHA256 | TLS 1.2 only. +| ECDHE-RSA-AES-256-CBC-SHA | +| ECDHE-RSA-AES-256-GCM-SHA384 | TLS 1.2 only. +| ECDHE-RSA-CHACHA20-POLY1205 | TLS 1.2 only. +| ECDHE-RSA-RC4-128-SHA | Disabled by default. RC4 not recommended. +| RSA-3DES-CBC3-SHA | +| RSA-AES-128-CBC-SHA | +| RSA-AES-128-CBC-SHA256 | TLS 1.2 only. Disabled by default. +| RSA-AES-128-GCM-SHA256 | TLS 1.2 only. +| RSA-AES-256-CBC-SHA | +| RSA-AES-256-GCM-SHA384 | TLS 1.2 only. +| RSA-RC4-128-SHA | Disabled by default. RC4 not recommended. +|=== + +Here is a list of acronyms used in defining the cipher suites: + +* 3DES: + Cipher suites using triple DES + +* AES-128/256: + Cipher suites using AES with 128/256-bit keys. + +* CBC: + Cipher using Cipher Block Chaining as block cipher mode. + +* ECDHE: + Cipher suites using Elliptic Curve Diffie-Hellman (DH) ephemeral key exchange. + +* ECDSA: + Cipher suites using Elliptic Curve Digital Signature Algorithm for authentication. + +* GCM: + Galois/Counter mode is used for symmetric key cryptography. + +* RC4: + Cipher suites using RC4. + +* RSA: + Cipher suites using RSA. + +* SHA, SHA256, SHA384: + Cipher suites using SHA-1, SHA-256 or SHA-384. +// end::cipher_suites[] + +[float] +[[curve-types]] +==== `curve_types` + +The list of curve types for ECDHE (Elliptic Curve Diffie-Hellman ephemeral key exchange). + +The following elliptic curve types are available: + +* P-256 +* P-384 +* P-521 +* X25519 [float] +[[ca-sha256]] +==== `ca_sha256` + +This configures a certificate pin that you can use to ensure that a specific certificate is part of the verified chain. + +The pin is a base64 encoded string of the SHA-256 of the certificate. + +NOTE: This check is not a replacement for the normal SSL validation, but it adds additional validation. +If this option is used with `verification_mode` set to `none`, the check will always fail because +it will not receive any verified chains. + +[discrete] +[[ssl-client-config]] +=== Client configuration options + +In the +{beatname_lc}.yml+ config file, you can specify the following client options in the +`ssl` section of each output that supports SSL. + +[float] +[[client-certificate-authorities]] ==== `certificate_authorities` -The list of root certificates for server verifications. If `certificate_authorities` is empty or not set, the trusted certificate authorities of the host system are used. If `certificate_authorities` is self-signed, the host system needs to trust that CA cert as well. -By default you can specify a list of files that +{beatname_lc} will read, but you can also embed a certificate directly in the `YAML` configuration: +The list of root certificates for server verifications is optional. If `certificate_authorities` is empty or not set, the +system keystore is used. If `certificate_authorities` is self-signed, the host system +needs to trust that CA cert as well. + +By default you can specify a list of files that +{beatname_lc}+ will read, but you +can also embed a certificate directly in the `YAML` configuration: [source,yaml] ---- @@ -133,16 +262,17 @@ certificate_authorities: ---- [float] -[[certificate]] +[[client-certificate]] ==== `certificate: "/etc/pki/client/cert.pem"` -The path to the certificate for SSL client authentication. If the certificate +The path to the certificate for SSL client authentication is only required if +`client_authentication` is specified. If the certificate is not specified, client authentication is not available. The connection might fail if the server requests client authentication. If the SSL server does not require client authentication, the certificate will be loaded, but not requested or used by the server. -When this option is configured, the <> option is also required. +When this option is configured, the <> option is also required. The certificate option support embedding of the certificate: [source,yaml] @@ -169,12 +299,11 @@ certificate: | -----END CERTIFICATE----- ---- - [float] -[[key]] +[[client-key]] ==== `key: "/etc/pki/client/cert.key"` -The client certificate key used for client authentication. This option is required if <> is specified. +The client certificate key used for client authentication. This option is only required if `client_authentication` is enabled. The key option support embedding of the private key: [source,yaml] @@ -211,157 +340,225 @@ key: | ---- [float] -==== `key_passphrase` - -The passphrase used to decrypt an encrypted key stored in the configured `key` file. - -[float] -==== `supported_protocols` - -List of allowed SSL/TLS versions. If SSL/TLS server decides for protocol versions -not configured, the connection will be dropped during or after the handshake. The -setting is a list of allowed protocol versions: -`SSLv3`, `TLSv1` for TLS version 1.0, `TLSv1.0`, `TLSv1.1`, `TLSv1.2`, and -`TLSv1.3`. - -The default value is `[TLSv1.1, TLSv1.2, TLSv1.3]`. - -[float] +[[client-verification-mode]] ==== `verification_mode` -Controls the verification of certificates. Valid values are: +Controls the verification of server certificates. Valid values are: - * `full`, which verifies that the provided certificate is signed by a trusted +`full`:: +Verifies that the provided certificate is signed by a trusted authority (CA) and also verifies that the server's hostname (or IP address) matches the names identified within the certificate. - * `strict`, which verifies that the provided certificate is signed by a trusted + +`strict`:: +Verifies that the provided certificate is signed by a trusted authority (CA) and also verifies that the server's hostname (or IP address) matches the names identified within the certificate. If the Subject Alternative Name is empty, it returns an error. - * `certificate`, which verifies that the provided certificate is signed by a + +`certificate`:: +Verifies that the provided certificate is signed by a trusted authority (CA), but does not perform any hostname verification. - * `none`, which performs _no verification_ of the server's certificate. This + +`none`:: +Performs _no verification_ of the server's certificate. This mode disables many of the security benefits of SSL/TLS and should only be used after very careful consideration. It is primarily intended as a temporary diagnostic mechanism when attempting to resolve TLS errors; its use in production environments is strongly discouraged. - ++ The default value is `full`. -[float] -==== `cipher_suites` +[discrete] +[[ssl-server-config]] +=== Server configuration options -The list of cipher suites to use. The first entry has the highest priority. -If this option is omitted, the Go crypto library's https://golang.org/pkg/crypto/tls/[default suites] -are used (recommended). Note that TLS 1.3 cipher suites are not -individually configurable in Go, so they are not included in this list. +In the +{beatname_lc}.yml+ config file, you can specify the following server options in the +`ssl` section of each output that supports SSL. -// tag::cipher_suites[] -The following cipher suites are available: - -[options="header"] -|=== -| Cypher | Notes -| ECDHE-ECDSA-AES-128-CBC-SHA | -| ECDHE-ECDSA-AES-128-CBC-SHA256 | TLS 1.2 only. Disabled by default. -| ECDHE-ECDSA-AES-128-GCM-SHA256 | TLS 1.2 only. -| ECDHE-ECDSA-AES-256-CBC-SHA | -| ECDHE-ECDSA-AES-256-GCM-SHA384 | TLS 1.2 only. -| ECDHE-ECDSA-CHACHA20-POLY1305 | TLS 1.2 only. -| ECDHE-ECDSA-RC4-128-SHA | Disabled by default. RC4 not recommended. -| ECDHE-RSA-3DES-CBC3-SHA | -| ECDHE-RSA-AES-128-CBC-SHA | -| ECDHE-RSA-AES-128-CBC-SHA256 | TLS 1.2 only. Disabled by default. -| ECDHE-RSA-AES-128-GCM-SHA256 | TLS 1.2 only. -| ECDHE-RSA-AES-256-CBC-SHA | -| ECDHE-RSA-AES-256-GCM-SHA384 | TLS 1.2 only. -| ECDHE-RSA-CHACHA20-POLY1205 | TLS 1.2 only. -| ECDHE-RSA-RC4-128-SHA | Disabled by default. RC4 not recommended. -| RSA-3DES-CBC3-SHA | -| RSA-AES-128-CBC-SHA | -| RSA-AES-128-CBC-SHA256 | TLS 1.2 only. Disabled by default. -| RSA-AES-128-GCM-SHA256 | TLS 1.2 only. -| RSA-AES-256-CBC-SHA | -| RSA-AES-256-GCM-SHA384 | TLS 1.2 only. -| RSA-RC4-128-SHA | Disabled by default. RC4 not recommended. -|=== +[float] +[[server-certificate-authorities]] +==== `certificate_authorities` -Here is a list of acronyms used in defining the cipher suites: +The list of root certificates for server verifications is optional and is only active if +`client_authentication` is enabled. If `certificate_authorities` is empty or not set, and `client_authentication` is not enabled, +the system keystore is used. -* 3DES: - Cipher suites using triple DES +If `certificate_authorities` is self-signed, the host system needs to trust that CA cert as well. +By default you can specify a list of files that +{beatname_lc}+ will read, but you can also embed a certificate +directly in the `YAML` configuration: -* AES-128/256: - Cipher suites using AES with 128/256-bit keys. +[source,yaml] +---- +certificate_authorities: + - | + -----BEGIN CERTIFICATE----- + MIIDCjCCAfKgAwIBAgITJ706Mu2wJlKckpIvkWxEHvEyijANBgkqhkiG9w0BAQsF + ADAUMRIwEAYDVQQDDAlsb2NhbGhvc3QwIBcNMTkwNzIyMTkyOTA0WhgPMjExOTA2 + MjgxOTI5MDRaMBQxEjAQBgNVBAMMCWxvY2FsaG9zdDCCASIwDQYJKoZIhvcNAQEB + BQADggEPADCCAQoCggEBANce58Y/JykI58iyOXpxGfw0/gMvF0hUQAcUrSMxEO6n + fZRA49b4OV4SwWmA3395uL2eB2NB8y8qdQ9muXUdPBWE4l9rMZ6gmfu90N5B5uEl + 94NcfBfYOKi1fJQ9i7WKhTjlRkMCgBkWPkUokvBZFRt8RtF7zI77BSEorHGQCk9t + /D7BS0GJyfVEhftbWcFEAG3VRcoMhF7kUzYwp+qESoriFRYLeDWv68ZOvG7eoWnP + PsvZStEVEimjvK5NSESEQa9xWyJOmlOKXhkdymtcUd/nXnx6UTCFgnkgzSdTWV41 + CI6B6aJ9svCTI2QuoIq2HxX/ix7OvW1huVmcyHVxyUECAwEAAaNTMFEwHQYDVR0O + BBYEFPwN1OceFGm9v6ux8G+DZ3TUDYxqMB8GA1UdIwQYMBaAFPwN1OceFGm9v6ux + 8G+DZ3TUDYxqMA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQELBQADggEBAG5D + 874A4YI7YUwOVsVAdbWtgp1d0zKcPRR+r2OdSbTAV5/gcS3jgBJ3i1BN34JuDVFw + 3DeJSYT3nxy2Y56lLnxDeF8CUTUtVQx3CuGkRg1ouGAHpO/6OqOhwLLorEmxi7tA + H2O8mtT0poX5AnOAhzVy7QW0D/k4WaoLyckM5hUa6RtvgvLxOwA0U+VGurCDoctu + 8F4QOgTAWyh8EZIwaKCliFRSynDpv3JTUwtfZkxo6K6nce1RhCWFAsMvDZL8Dgc0 + yvgJ38BRsFOtkRuAGSf6ZUwTO8JJRRIFnpUzXflAnGivK9M13D5GEQMmIl6U9Pvk + sxSmbIUfc2SGJGCJD4I= + -----END CERTIFICATE----- +---- -* CBC: - Cipher using Cipher Block Chaining as block cipher mode. +[float] +[[server-certificate]] +==== `certificate: "/etc/pki/server/cert.pem"` -* ECDHE: - Cipher suites using Elliptic Curve Diffie-Hellman (DH) ephemeral key exchange. +The path to the certificate for SSL authentication is required. If the certificate +is not specified, client authentication is not available. The connection +might fail if the server requests client authentication. If the SSL server does not +require client authentication, the certificate will be loaded, but not requested or used +by the server. -* ECDSA: - Cipher suites using Elliptic Curve Digital Signature Algorithm for authentication. +When this option is configured, the <> option is also required. +The certificate option support embedding of the certificate: -* GCM: - Galois/Counter mode is used for symmetric key cryptography. +[source,yaml] +---- +certificate: | + -----BEGIN CERTIFICATE----- + MIIDCjCCAfKgAwIBAgITJ706Mu2wJlKckpIvkWxEHvEyijANBgkqhkiG9w0BAQsF + ADAUMRIwEAYDVQQDDAlsb2NhbGhvc3QwIBcNMTkwNzIyMTkyOTA0WhgPMjExOTA2 + MjgxOTI5MDRaMBQxEjAQBgNVBAMMCWxvY2FsaG9zdDCCASIwDQYJKoZIhvcNAQEB + BQADggEPADCCAQoCggEBANce58Y/JykI58iyOXpxGfw0/gMvF0hUQAcUrSMxEO6n + fZRA49b4OV4SwWmA3395uL2eB2NB8y8qdQ9muXUdPBWE4l9rMZ6gmfu90N5B5uEl + 94NcfBfYOKi1fJQ9i7WKhTjlRkMCgBkWPkUokvBZFRt8RtF7zI77BSEorHGQCk9t + /D7BS0GJyfVEhftbWcFEAG3VRcoMhF7kUzYwp+qESoriFRYLeDWv68ZOvG7eoWnP + PsvZStEVEimjvK5NSESEQa9xWyJOmlOKXhkdymtcUd/nXnx6UTCFgnkgzSdTWV41 + CI6B6aJ9svCTI2QuoIq2HxX/ix7OvW1huVmcyHVxyUECAwEAAaNTMFEwHQYDVR0O + BBYEFPwN1OceFGm9v6ux8G+DZ3TUDYxqMB8GA1UdIwQYMBaAFPwN1OceFGm9v6ux + 8G+DZ3TUDYxqMA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQELBQADggEBAG5D + 874A4YI7YUwOVsVAdbWtgp1d0zKcPRR+r2OdSbTAV5/gcS3jgBJ3i1BN34JuDVFw + 3DeJSYT3nxy2Y56lLnxDeF8CUTUtVQx3CuGkRg1ouGAHpO/6OqOhwLLorEmxi7tA + H2O8mtT0poX5AnOAhzVy7QW0D/k4WaoLyckM5hUa6RtvgvLxOwA0U+VGurCDoctu + 8F4QOgTAWyh8EZIwaKCliFRSynDpv3JTUwtfZkxo6K6nce1RhCWFAsMvDZL8Dgc0 + yvgJ38BRsFOtkRuAGSf6ZUwTO8JJRRIFnpUzXflAnGivK9M13D5GEQMmIl6U9Pvk + sxSmbIUfc2SGJGCJD4I= + -----END CERTIFICATE----- +---- -* RC4: - Cipher suites using RC4. +[float] +[[server-key]] +==== `key: "/etc/pki/server/cert.key"` -* RSA: - Cipher suites using RSA. +The server certificate key used for authentication is required. +The key option support embedding of the private key: -* SHA, SHA256, SHA384: - Cipher suites using SHA-1, SHA-256 or SHA-384. -// end::cipher_suites[] +[source,yaml] +---- +key: | + -----BEGIN PRIVATE KEY----- + MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDXHufGPycpCOfI + sjl6cRn8NP4DLxdIVEAHFK0jMRDup32UQOPW+DleEsFpgN9/ebi9ngdjQfMvKnUP + Zrl1HTwVhOJfazGeoJn7vdDeQebhJfeDXHwX2DiotXyUPYu1ioU45UZDAoAZFj5F + KJLwWRUbfEbRe8yO+wUhKKxxkApPbfw+wUtBicn1RIX7W1nBRABt1UXKDIRe5FM2 + MKfqhEqK4hUWC3g1r+vGTrxu3qFpzz7L2UrRFRIpo7yuTUhEhEGvcVsiTppTil4Z + HcprXFHf5158elEwhYJ5IM0nU1leNQiOgemifbLwkyNkLqCKth8V/4sezr1tYblZ + nMh1cclBAgMBAAECggEBAKdP5jyOicqknoG9/G564RcDsDyRt64NuO7I6hBg7SZx + Jn7UKWDdFuFP/RYtoabn6QOxkVVlydp5Typ3Xu7zmfOyss479Q/HIXxmmbkD0Kp0 + eRm2KN3y0b6FySsS40KDRjKGQCuGGlNotW3crMw6vOvvsLTlcKgUHF054UVCHoK/ + Piz7igkDU7NjvJeha53vXL4hIjb10UtJNaGPxIyFLYRZdRPyyBJX7Yt3w8dgz8WM + epOPu0dq3bUrY3WQXcxKZo6sQjE1h7kdl4TNji5jaFlvD01Y8LnyG0oThOzf0tve + Gaw+kuy17gTGZGMIfGVcdeb+SlioXMAAfOps+mNIwTECgYEA/gTO8W0hgYpOQJzn + BpWkic3LAoBXWNpvsQkkC3uba8Fcps7iiEzotXGfwYcb5Ewf5O3Lrz1EwLj7GTW8 + VNhB3gb7bGOvuwI/6vYk2/dwo84bwW9qRWP5hqPhNZ2AWl8kxmZgHns6WTTxpkRU + zrfZ5eUrBDWjRU2R8uppgRImsxMCgYEA2MxuL/C/Ko0d7XsSX1kM4JHJiGpQDvb5 + GUrlKjP/qVyUysNF92B9xAZZHxxfPWpdfGGBynhw7X6s+YeIoxTzFPZVV9hlkpAA + 5igma0n8ZpZEqzttjVdpOQZK8o/Oni/Q2S10WGftQOOGw5Is8+LY30XnLvHBJhO7 + TKMurJ4KCNsCgYAe5TDSVmaj3dGEtFC5EUxQ4nHVnQyCpxa8npL+vor5wSvmsfUF + hO0s3GQE4sz2qHecnXuPldEd66HGwC1m2GKygYDk/v7prO1fQ47aHi9aDQB9N3Li + e7Vmtdn3bm+lDjtn0h3Qt0YygWj+wwLZnazn9EaWHXv9OuEMfYxVgYKpdwKBgEze + Zy8+WDm5IWRjn8cI5wT1DBT/RPWZYgcyxABrwXmGZwdhp3wnzU/kxFLAl5BKF22T + kRZ+D+RVZvVutebE9c937BiilJkb0AXLNJwT9pdVLnHcN2LHHHronUhV7vetkop+ + kGMMLlY0lkLfoGq1AxpfSbIea9KZam6o6VKxEnPDAoGAFDCJm+ZtsJK9nE5GEMav + NHy+PwkYsHhbrPl4dgStTNXLenJLIJ+Ke0Pcld4ZPfYdSyu/Tv4rNswZBNpNsW9K + 0NwJlyMBfayoPNcJKXrH/csJY7hbKviAHr1eYy9/8OL0dHf85FV+9uY5YndLcsDc + nygO9KTJuUiBrLr0AHEnqko= + -----END PRIVATE KEY----- +---- [float] -==== `curve_types` - -The list of curve types for ECDHE (Elliptic Curve Diffie-Hellman ephemeral key exchange). +[[server-verification-mode]] +==== `verification_mode` -The following elliptic curve types are available: +Controls the verification of client certificates. Valid values are: -* P-256 -* P-384 -* P-521 -* X25519 - -[float] -==== `renegotiation` +`full`:: +Verifies that the provided certificate is signed by a trusted +authority (CA) and also verifies that the server's hostname (or IP address) +matches the names identified within the certificate. -This configures what types of TLS renegotiation are supported. The valid options -are `never`, `once`, and `freely`. The default value is never. +`strict`:: +Verifies that the provided certificate is signed by a trusted +authority (CA) and also verifies that the server's hostname (or IP address) +matches the names identified within the certificate. If the Subject Alternative +Name is empty, it returns an error. -* `never` - Disables renegotiation. -* `once` - Allows a remote server to request renegotiation once per connection. -* `freely` - Allows a remote server to repeatedly request renegotiation. +`certificate`:: +Verifies that the provided certificate is signed by a +trusted authority (CA), but does not perform any hostname verification. +`none`:: +Performs _no verification_ of the server's certificate. This +mode disables many of the security benefits of SSL/TLS and should only be used +after very careful consideration. It is primarily intended as a temporary +diagnostic mechanism when attempting to resolve TLS errors; its use in +production environments is strongly discouraged. ++ +The default value is `full`. [float] -==== `ca_sha256` +[[server-renegotiation]] +==== `renegotiation` -This configures a certificate pin that you can use to ensure that a specific certificate is part of the verified chain. +This configures what types of TLS renegotiation are supported. The valid options +are: -The pin is a base64 encoded string of the SHA-256 of the certificate. +`never`:: +Disables renegotiation. -NOTE: This check is not a replacement for the normal SSL validation, but it adds additional validation. -If this option is used with `verification_mode` set to `none`, the check will always fail because -it will not receive any verified chains. +`once`:: +Allows a remote server to request renegotiation once per connection. +`freely`:: +Allows a remote server to repeatedly request renegotiation. ++ +The default value is `never`. ifeval::["{beatname_lc}" == "filebeat"] [float] +[[server-client-renegotiation]] ==== `client_authentication` -This configures what types of client authentication are supported. The valid options -are `none`, `optional`, and `required`. When `certificate_authorities` is set it will -default to `required` otherwise it will be set to `none`. +The type of client authentication mode. When `certificate_authorities` is set, it +defaults to `required`, otherwise it defaults to `none`. + +[NOTE] +===== +This option is only valid with the TCP or the Syslog input. +===== + +The valid options are: + +`none`:: +Disables client authentication. -NOTE: This option is only valid with the TCP or the Syslog input. +`optional`:: +When a client certificate is given, the server will verify it. -* `none` - Disables client authentication. -* `optional` - When a client certificate is given, the server will verify it. -* `required` - Will require clients to provide a valid certificate. +`required`:: +Will require clients to provide a valid certificate. endif::[] From 081a3a128f3ebe5e39ad2f069022bb7f17039c54 Mon Sep 17 00:00:00 2001 From: Eamonn Smith Date: Mon, 8 Mar 2021 13:33:24 +0000 Subject: [PATCH 2/4] Edits following review --- libbeat/docs/shared-ssl-config.asciidoc | 57 +++++++++++++------------ 1 file changed, 29 insertions(+), 28 deletions(-) diff --git a/libbeat/docs/shared-ssl-config.asciidoc b/libbeat/docs/shared-ssl-config.asciidoc index 757aa3639ee..fb161f91613 100644 --- a/libbeat/docs/shared-ssl-config.asciidoc +++ b/libbeat/docs/shared-ssl-config.asciidoc @@ -91,8 +91,7 @@ endif::[] [[ssl-common-config]] === Common configuration options -In the +{beatname_lc}.yml+ config file, you can specify the following common options in the -`ssl` section of each output that supports SSL. +You can specify the following options in the `ssl` section of the +{beatname_lc}.yml+ config file. [float] [[enabled]] @@ -106,12 +105,6 @@ SSL settings are disabled if either `enabled` is set to `false` or the `ssl` section is missing. ===== -[float] -[[key-passphrase]] -==== `key_passphrase` - -The passphrase used to decrypt an encrypted key stored in the configured `key` file. - [float] [[supported-protocols]] ==== `supported_protocols` @@ -222,14 +215,13 @@ it will not receive any verified chains. [[ssl-client-config]] === Client configuration options -In the +{beatname_lc}.yml+ config file, you can specify the following client options in the -`ssl` section of each output that supports SSL. +You can specify the following options in the `ssl` section of the +{beatname_lc}.yml+ config file. [float] [[client-certificate-authorities]] ==== `certificate_authorities` -The list of root certificates for server verifications is optional. If `certificate_authorities` is empty or not set, the +The list of root certificates for verifications is required. If `certificate_authorities` is empty or not set, the system keystore is used. If `certificate_authorities` is self-signed, the host system needs to trust that CA cert as well. @@ -303,8 +295,8 @@ certificate: | [[client-key]] ==== `key: "/etc/pki/client/cert.key"` -The client certificate key used for client authentication. This option is only required if `client_authentication` is enabled. -The key option support embedding of the private key: +The client certificate key used for client authentication and is only required +if `client_authentication` is configured. The key option support embedding of the private key: [source,yaml] ---- @@ -339,6 +331,13 @@ key: | -----END PRIVATE KEY----- ---- +[float] +[[client-key-passphrase]] +==== `key_passphrase` + +The passphrase used to decrypt an encrypted key stored in the configured `key` file. + + [float] [[client-verification-mode]] ==== `verification_mode` @@ -363,7 +362,7 @@ trusted authority (CA), but does not perform any hostname verification. `none`:: Performs _no verification_ of the server's certificate. This mode disables many of the security benefits of SSL/TLS and should only be used -after very careful consideration. It is primarily intended as a temporary +after cautious consideration. It is primarily intended as a temporary diagnostic mechanism when attempting to resolve TLS errors; its use in production environments is strongly discouraged. + @@ -373,16 +372,15 @@ The default value is `full`. [[ssl-server-config]] === Server configuration options -In the +{beatname_lc}.yml+ config file, you can specify the following server options in the -`ssl` section of each output that supports SSL. +You can specify the following options in the `ssl` section of the +{beatname_lc}.yml+ config file. [float] [[server-certificate-authorities]] ==== `certificate_authorities` -The list of root certificates for server verifications is optional and is only active if -`client_authentication` is enabled. If `certificate_authorities` is empty or not set, and `client_authentication` is not enabled, -the system keystore is used. +The list of root certificates for server verifications is only required if +`client_authentication` is configured. If `certificate_authorities` is empty or not set, and +`client_authentication` is not configured, the system keystore is used. If `certificate_authorities` is self-signed, the host system needs to trust that CA cert as well. By default you can specify a list of files that +{beatname_lc}+ will read, but you can also embed a certificate @@ -418,10 +416,7 @@ certificate_authorities: ==== `certificate: "/etc/pki/server/cert.pem"` The path to the certificate for SSL authentication is required. If the certificate -is not specified, client authentication is not available. The connection -might fail if the server requests client authentication. If the SSL server does not -require client authentication, the certificate will be loaded, but not requested or used -by the server. +is not specified, server authentication is not available. When this option is configured, the <> option is also required. The certificate option support embedding of the certificate: @@ -490,6 +485,12 @@ key: | -----END PRIVATE KEY----- ---- +[float] +[[server-key-passphrase]] +==== `key_passphrase` + +The passphrase is used to decrypt an encrypted key stored in the configured `key` file. + [float] [[server-verification-mode]] ==== `verification_mode` @@ -514,7 +515,7 @@ trusted authority (CA), but does not perform any hostname verification. `none`:: Performs _no verification_ of the server's certificate. This mode disables many of the security benefits of SSL/TLS and should only be used -after very careful consideration. It is primarily intended as a temporary +after cautious consideration. It is primarily intended as a temporary diagnostic mechanism when attempting to resolve TLS errors; its use in production environments is strongly discouraged. + @@ -534,7 +535,7 @@ Disables renegotiation. Allows a remote server to request renegotiation once per connection. `freely`:: -Allows a remote server to repeatedly request renegotiation. +Allows a remote server to request renegotiation repeatedly. + The default value is `never`. @@ -544,11 +545,11 @@ ifeval::["{beatname_lc}" == "filebeat"] ==== `client_authentication` The type of client authentication mode. When `certificate_authorities` is set, it -defaults to `required`, otherwise it defaults to `none`. +defaults to `required`. Otherwise, it defaults to `none`. [NOTE] ===== -This option is only valid with the TCP or the Syslog input. +This option is only valid with the HTTP Endpoint, HTTP JSON, MQTT, Syslog, and the TCP input. ===== The valid options are: @@ -557,7 +558,7 @@ The valid options are: Disables client authentication. `optional`:: -When a client certificate is given, the server will verify it. +When a client certificate is supplied, the server will verify it. `required`:: Will require clients to provide a valid certificate. From 02822cbae6674e01b8f50497189fd488eb0c0444 Mon Sep 17 00:00:00 2001 From: Eamonn Smith Date: Tue, 9 Mar 2021 09:03:57 +0000 Subject: [PATCH 3/4] Review edits --- libbeat/docs/shared-ssl-config.asciidoc | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/libbeat/docs/shared-ssl-config.asciidoc b/libbeat/docs/shared-ssl-config.asciidoc index fb161f91613..b1ab997dacd 100644 --- a/libbeat/docs/shared-ssl-config.asciidoc +++ b/libbeat/docs/shared-ssl-config.asciidoc @@ -87,17 +87,24 @@ Example module with SSL enabled: ---- endif::[] +There are a number of SSL configuration options available to you: + +* <> +* <> +* <> + [discrete] [[ssl-common-config]] === Common configuration options +Common SSL configuration options can be used in both client and server configurations. You can specify the following options in the `ssl` section of the +{beatname_lc}.yml+ config file. [float] [[enabled]] ==== `enabled` -To disable the ssl configuration, set the value to `false`. The default value is `true`. +To disable SSL configuration, set the value to `false`. The default value is `true`. [NOTE] ===== From 04ed90482b476578bf64ac7da15dd8dd9346bd06 Mon Sep 17 00:00:00 2001 From: Eamonn Smith Date: Wed, 10 Mar 2021 09:36:14 +0000 Subject: [PATCH 4/4] Updates following review --- libbeat/docs/shared-ssl-config.asciidoc | 22 ++++++++++------------ 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/libbeat/docs/shared-ssl-config.asciidoc b/libbeat/docs/shared-ssl-config.asciidoc index b1ab997dacd..ec0690397a5 100644 --- a/libbeat/docs/shared-ssl-config.asciidoc +++ b/libbeat/docs/shared-ssl-config.asciidoc @@ -98,7 +98,8 @@ There are a number of SSL configuration options available to you: === Common configuration options Common SSL configuration options can be used in both client and server configurations. -You can specify the following options in the `ssl` section of the +{beatname_lc}.yml+ config file. +You can specify the following options in the `ssl` section of each subsystem that +supports SSL. [float] [[enabled]] @@ -222,7 +223,8 @@ it will not receive any verified chains. [[ssl-client-config]] === Client configuration options -You can specify the following options in the `ssl` section of the +{beatname_lc}.yml+ config file. +You can specify the following options in the `ssl` section of each subsystem that +supports SSL. [float] [[client-certificate-authorities]] @@ -379,15 +381,16 @@ The default value is `full`. [[ssl-server-config]] === Server configuration options -You can specify the following options in the `ssl` section of the +{beatname_lc}.yml+ config file. +You can specify the following options in the `ssl` section of each subsystem that +supports SSL. [float] [[server-certificate-authorities]] ==== `certificate_authorities` -The list of root certificates for server verifications is only required if +The list of root certificates for client verifications is only required if `client_authentication` is configured. If `certificate_authorities` is empty or not set, and -`client_authentication` is not configured, the system keystore is used. +`client_authentication` is configured, the system keystore is used. If `certificate_authorities` is self-signed, the host system needs to trust that CA cert as well. By default you can specify a list of files that +{beatname_lc}+ will read, but you can also embed a certificate @@ -422,8 +425,8 @@ certificate_authorities: [[server-certificate]] ==== `certificate: "/etc/pki/server/cert.pem"` -The path to the certificate for SSL authentication is required. If the certificate -is not specified, server authentication is not available. +For server authentication, the path to the SSL authentication certificate must +be specified for TLS. If the certificate is not specified, startup will fail. When this option is configured, the <> option is also required. The certificate option support embedding of the certificate: @@ -554,11 +557,6 @@ ifeval::["{beatname_lc}" == "filebeat"] The type of client authentication mode. When `certificate_authorities` is set, it defaults to `required`. Otherwise, it defaults to `none`. -[NOTE] -===== -This option is only valid with the HTTP Endpoint, HTTP JSON, MQTT, Syslog, and the TCP input. -===== - The valid options are: `none`::