From 397a33ac8e4aff2cb7c1dd302896865e5afe43e1 Mon Sep 17 00:00:00 2001 From: Hiroshi Hatake Date: Fri, 28 Jun 2024 07:24:08 +0900 Subject: [PATCH] tls: Add descriptions for x509v3 alt name verification (tls.verify_hostname) (#1393) * tls: Add a description for tls.verify_hostname parameter Signed-off-by: Hiroshi Hatake * filter_kubernetes: Add a description for tls.verify_hostname Signed-off-by: Hiroshi Hatake * Address comments Co-authored-by: Pat Signed-off-by: Hiroshi Hatake --------- Signed-off-by: Hiroshi Hatake Co-authored-by: Pat --- administration/transport-security.md | 40 ++++++++++++++++++++++++++++ pipeline/filters/kubernetes.md | 1 + 2 files changed, 41 insertions(+) diff --git a/administration/transport-security.md b/administration/transport-security.md index f2a644c8a..4443cfd70 100644 --- a/administration/transport-security.md +++ b/administration/transport-security.md @@ -9,6 +9,7 @@ Both input and output plugins that perform Network I/O can optionally enable TLS | :--- | :--- | :--- | | tls | enable or disable TLS support | Off | | tls.verify | force certificate validation | On | +| tls.verify\_hostname | force TLS verification of hostnames | Off | | tls.debug | Set TLS debug verbosity level. It accept the following values: 0 \(No debug\), 1 \(Error\), 2 \(State change\), 3 \(Informational\) and 4 Verbose | 1 | | tls.ca\_file | absolute path to CA certificate file | | | tls.ca\_path | absolute path to scan for certificate files | | @@ -171,3 +172,42 @@ Fluent Bit supports [TLS server name indication](https://en.wikipedia.org/wiki/S tls.ca_file /etc/certs/fluent.crt tls.vhost fluent.example.com ``` + +### Verify subjectAltName + +By default, TLS verification of hostnames is not done automatically. +As an example, we can extract the X509v3 Subject Alternative Name from a certificate: + +``` +X509v3 Subject Alternative Name: + DNS:my.fluent-aggregator.net +``` + +As you can see, this certificate covers only `my.fluent-aggregator.net` so if we use a different hostname it should fail. + +To fully verify the alternative name and demonstrate the failure we enable `tls.verify_hostname`: + + +```text +[INPUT] + Name cpu + Tag cpu + +[OUTPUT] + Name forward + Match * + Host other.fluent-aggregator.net + Port 24224 + tls On + tls.verify On + tls.verify_hostname on + tls.ca_file /path/to/fluent-x509v3-alt-name.crt +``` + +This outgoing connect will be failed and disconnected: + +``` +[2024/06/17 16:51:31] [error] [tls] error: unexpected EOF with reason: certificate verify failed +[2024/06/17 16:51:31] [debug] [upstream] connection #50 failed to other.fluent-aggregator.net:24224 +[2024/06/17 16:51:31] [error] [output:forward:forward.0] no upstream connections available +``` diff --git a/pipeline/filters/kubernetes.md b/pipeline/filters/kubernetes.md index 3a352eadb..d4ad92b1b 100644 --- a/pipeline/filters/kubernetes.md +++ b/pipeline/filters/kubernetes.md @@ -37,6 +37,7 @@ The plugin supports the following configuration parameters: | Keep\_Log | When `Keep_Log` is disabled, the `log` field is removed from the incoming message once it has been successfully merged \(`Merge_Log` must be enabled as well\). | On | | tls.debug | Debug level between 0 \(nothing\) and 4 \(every detail\). | -1 | | tls.verify | When enabled, turns on certificate validation when connecting to the Kubernetes API server. | On | +| tls.verify\_hostname | When enabled, turns on hostname validation for certificates | Off | | Use\_Journal | When enabled, the filter reads logs coming in Journald format. | Off | | Cache\_Use\_Docker\_Id | When enabled, metadata will be fetched from K8s when docker\_id is changed. | Off | | Regex\_Parser | Set an alternative Parser to process record Tag and extract pod\_name, namespace\_name, container\_name and docker\_id. The parser must be registered in a [parsers file](https://github.com/fluent/fluent-bit/blob/master/conf/parsers.conf) \(refer to parser _filter-kube-test_ as an example\). | |