From dade05d2c3cf79fdc90392f73bc9dd602f9c3660 Mon Sep 17 00:00:00 2001 From: John Floren Date: Fri, 13 Sep 2024 16:11:10 -0700 Subject: [PATCH 1/2] Document SANs in certificates Addresses #1110 --- configuration/certificates.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/configuration/certificates.md b/configuration/certificates.md index 58311054..0dbd1296 100644 --- a/configuration/certificates.md +++ b/configuration/certificates.md @@ -10,6 +10,22 @@ The Gravwell administrator has three options for certificates: * Install a properly-signed TLS certificate. This is the ideal configuration, but typically requires the Gravwell instance to have a publicly-accessible hostname. * Install a self-signed certificate. This makes sense when you want to encrypt traffic to Gravwell but for one reason or another cannot get a properly signed certificate. +## Hostnames in TLS Certificates + +When connecting to a TLS-secured service, the client will check that the server's certificate is valid for the *hostname* the client is trying to access. If you have a valid certificate for `gravwell.example.org`, but you decide to access your Gravwell server directly by IP, e.g. `https://10.0.0.2/`, your web browser will most likely warn you that the certificate presented is invalid. Components of a Gravwell cluster may also communicate with each other over TLS-secured connections, and unless they are specifically configured to skip certificate validation these services will *fail* if the hostname they are given doesn't match the names on the certificate. + +When provisioning your TLS certificates, make sure the Common Name (CN) and Subject Alternative Names (SANs) cover *all* hostnames or IP addresses you will ever use to connect to the system. If you have multiple DNS entries for the same system -- for example, if your webserver is accessible from both the Internet and within your own LAN namespace -- be sure all those names are in the certificate! + +Here's a brief list of some of the ways Gravwell components communicate via TLS connections; make sure your certificates are appropriate for any of these situations you intend to deploy: + +- Ingesters talk to indexers (`Encrypted-Backend-Target` in the [ingester config file](/ingesters/ingesters)) +- Indexers talk to other indexers via [replication](/configuration/replication) +- Indexers talk to the [cloud archive service](/configuration/archive) +- Webservers in a cluster talk to the [datastore](/distributed/frontend) +- Webservers in a cluster talk to other webservers (`External-Addr`, see [docs](/distributed/frontend)) + +Generally, you will see entries in the relevant component's log files if there is a TLS problem; if you see logs about invalid certificates, but you believe that your certificate should be correct, double-check the hostnames you've set in the config files against the hostnames present in the certificate's CN and SAN fields. + ## Allowed TLS Ciphers A number of TLS ciphers are considered cryptographically insecure, so Gravwell only supports the following TLS ciphers: From 90da6a023be33c1614bd0c5fe9cd0a4483278d88 Mon Sep 17 00:00:00 2001 From: John Floren <108435989+john-floren-gravwell@users.noreply.github.com> Date: Tue, 17 Sep 2024 15:23:58 -0700 Subject: [PATCH 2/2] Update certificates.md --- configuration/certificates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/configuration/certificates.md b/configuration/certificates.md index 0dbd1296..f771d115 100644 --- a/configuration/certificates.md +++ b/configuration/certificates.md @@ -14,7 +14,7 @@ The Gravwell administrator has three options for certificates: When connecting to a TLS-secured service, the client will check that the server's certificate is valid for the *hostname* the client is trying to access. If you have a valid certificate for `gravwell.example.org`, but you decide to access your Gravwell server directly by IP, e.g. `https://10.0.0.2/`, your web browser will most likely warn you that the certificate presented is invalid. Components of a Gravwell cluster may also communicate with each other over TLS-secured connections, and unless they are specifically configured to skip certificate validation these services will *fail* if the hostname they are given doesn't match the names on the certificate. -When provisioning your TLS certificates, make sure the Common Name (CN) and Subject Alternative Names (SANs) cover *all* hostnames or IP addresses you will ever use to connect to the system. If you have multiple DNS entries for the same system -- for example, if your webserver is accessible from both the Internet and within your own LAN namespace -- be sure all those names are in the certificate! +When provisioning your TLS certificates, make sure the Common Name (CN) and Subject Alternative Names (SANs) cover *all* hostnames or IP addresses you will ever use to connect to the system. If you have multiple DNS entries for the same system -- for example, if your webserver is accessible from both the Internet (`gravwell.example.org`) and within your own LAN namespace (`gravwell.internal.lan`) -- be sure all those names are in the certificate! Here's a brief list of some of the ways Gravwell components communicate via TLS connections; make sure your certificates are appropriate for any of these situations you intend to deploy: