From d0b79b50bb5002e39aba04266a36b9be2a261cb4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?No=C3=A9mi=20V=C3=A1nyi?= Date: Fri, 24 Apr 2020 17:36:25 +0200 Subject: [PATCH] init docs --- libbeat/docs/kerberos-config.asciidoc | 196 ++++++++++++++++++ .../elasticsearch/docs/elasticsearch.asciidoc | 6 + 2 files changed, 202 insertions(+) create mode 100644 libbeat/docs/kerberos-config.asciidoc diff --git a/libbeat/docs/kerberos-config.asciidoc b/libbeat/docs/kerberos-config.asciidoc new file mode 100644 index 000000000000..9ed37ba68f44 --- /dev/null +++ b/libbeat/docs/kerberos-config.asciidoc @@ -0,0 +1,196 @@ +[[configuration-kerberos]] +== Configure Kerberos + +You can specify Kerberos options with any output or input that supports Kerberos, like {es} and Kafka. + +Example output config with Kerberos password based authentication: + +[source,yaml] +---- +output.elasticsearch.hosts: ["http://my-elasticsearch:9200"] +output.elasticsearch.kerberos.auth_type: password +output.elasticsearch.kerberos.username: "elastic" +output.elasticsearch.kerberos.password: "changeme" +output.elasticsearch.kerberos.config_path: "/etc/krb5.conf" +output.elasticsearch.kerberos.realm: "ELASTIC.CO" +---- + +The service principal name for the Elasticsearch instance is contructed from these options. Based on this configuration +it is going to be `HTTP/my-elasticsearch@ELASTIC.CO`. + +[float] +=== Configuration options + +You can specify the following options in the `kerberos` section of the +{beatname_lc}.yml+ config file: + +[float] +==== `enabled` + +The `enabled` setting can be used to disable the kerberos configuration by setting +it to `false`. The default value is `true`. + +NOTE: SSL settings are disabled if either `enabled` is set to `false` or the +`ssl` section is missing. + +[float] +==== `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. + +[float] +[[certificate]] +==== `certificate: "/etc/pki/client/cert.pem"` + +The path to the certificate for SSL client authentication. 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. + +[float] +[[key]] +==== `key: "/etc/pki/client/cert.key"` + +The client certificate key used for client authentication. This option is required if <> is specified. + +[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] +==== `verification_mode` + +This option controls whether the client verifies server certificates and host +names. Valid values are `none` and `full`. If `verification_mode` is set +to `none`, all server host names and certificates are accepted. In this mode, +TLS-based connections are susceptible to man-in-the-middle attacks. Use this +option for testing only. + +The default is `full`. + +[float] +==== `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 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. + +The following cipher suites are available: + +* 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. + +[float] +==== `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] +==== `renegotiation` + +This configures what types of TLS renegotiation are supported. The valid options +are `never`, `once`, and `freely`. The default value is never. + +* `never` - Disables renegotiation. +* `once` - Allows a remote server to request renegotiation once per connection. +* `freely` - Allows a remote server to repeatedly request renegotiation. + + +[float] +==== `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. + + +ifeval::["{beatname_lc}" == "filebeat"] +[float] +==== `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`. + +NOTE: This option is only valid with the TCP or the Syslog input. + +* `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. +endif::[] + diff --git a/libbeat/outputs/elasticsearch/docs/elasticsearch.asciidoc b/libbeat/outputs/elasticsearch/docs/elasticsearch.asciidoc index c36e6b24163e..5c18a2b9a780 100644 --- a/libbeat/outputs/elasticsearch/docs/elasticsearch.asciidoc +++ b/libbeat/outputs/elasticsearch/docs/elasticsearch.asciidoc @@ -676,3 +676,9 @@ for HTTPS-based connections. If the `ssl` section is missing, the host CAs are u Elasticsearch. See <> for more information. + +===== `kebreros` + +Configuration options for Kerberos authentication. + +See <> for more information.