TLS

Galleon serves HTTPS itself when the configuration names a certificate and a key. A reverse proxy is not needed for that (Reverse proxy).

Enabling it

TLS is enabled by the server.tls block with two paths:

server:
  tls:
    cert_file: /etc/galleon/tls/fullchain.pem
    key_file: /etc/galleon/tls/privkey.pem

TLS is enabled when both paths are set. The GALLEON_SERVER_TLS_CERT_FILE and GALLEON_SERVER_TLS_KEY_FILE environment variables take the same values.

The requirements for the files:

• the certificate in PEM format. Inside the file the server certificate comes first, the intermediate certificates of the authority after it; ACME clients and cert-manager call such a file fullchain;
• the key in PEM format. Keys with a passphrase and keys in the OpenSSH format are not accepted;
• the key algorithm — RSA, ECDSA, or Ed25519.

Once TLS is on, Galleon reports addresses to clients with the https scheme. If the instance is reachable under a different name, set it in server.public_base_url.

Configuration errors

The server does not start when:

• only one of the two paths is set;
• a file cannot be read or holds the wrong format;
• the key is protected by a passphrase;
• an unknown key appears inside server.tls;
• the tls block ended up outside server.

Rotation

A certificate is replaced by a restart:

1. Put the new files at the same paths.
2. Restart Galleon; if there are several servers, restart each of them.
3. Make sure the intended certificate is live: at startup the log carries a tls: server certificate loaded record with an sha256 field.

Protocol settings

Connections are accepted over TLS 1.2 and newer. The cipher suites:

• TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256;
• TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256;
• TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384;
• TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384;
• TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256;
• TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256;
• TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256;
• TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256.

In TLS 1.3 the cipher suites are determined by the protocol itself.

Responses served over TLS carry the Strict-Transport-Security header with a one-year term and includeSubDomains. If the instance is later moved back to HTTP, browsers that already visited it over HTTPS will open the web interface only after the HSTS state is cleared.

Diagnostics

Failed TLS handshakes are written to the log at the warn level with the server.http source: the client could not negotiate a protocol version or a cipher. The record format is described in Logging.