Skip to main content

TLS encryption

By the end of this page you will have a certificate installed, ScramDB accepting encrypted connections on the PostgreSQL wire protocol, and a psql session you can confirm is actually encrypted.

What TLS covers​

TLS encrypts the PostgreSQL wire-protocol connection between a client and ScramDB. The server presents a certificate; the client can verify it. ScramDB does not request or verify a client certificate, so there is no mutual TLS (mTLS) mode: this is server-side TLS only, the same shape as a typical PostgreSQL deployment without clientcert verification turned on.

Step by step: enable TLS​

  1. Generate a self-signed certificate and key. For production, use a certificate from your own CA or a public one instead; this command is enough to prove the setup works end to end:

    openssl req -x509 -newkey rsa:4096 -sha256 -days 365 -nodes \
      -keyout server.key -out server.crt \
      -subj "/CN=scramdb.internal"

    Expected output: server.crt and server.key in the current directory, no prompts (the -nodes flag skips the passphrase).

  2. Place both files where ScramDB can read them, and set tls_cert and tls_key under [general] in your config TOML:

    [general]
    tls_cert = "/etc/scramdb/server.crt"
    tls_key = "/etc/scramdb/server.key"

    Both fields default to empty, which disables TLS entirely: setting either path is what turns encryption on.

  3. Restart ScramDB and check the log for a clean startup with no TLS-related fatal error.

  4. Connect with TLS required and confirm the handshake succeeds:

    psql "host=localhost port=5432 user=scramdb dbname=scramdb sslmode=require"

    Once connected, confirm the connection is actually encrypted:

    \conninfo

    Expected output includes SSL connection (protocol: TLSv1.3, ...). If TLS were not active, \conninfo would report the connection as not using SSL, or sslmode=require would have refused to connect at all.

Failure modes​

A missing file, an unreadable file, a malformed PEM, or a certificate/key pair that don't match one another all fail the same way: the process panics at startup and does not start. ScramDB does not fall back to plaintext when TLS is misconfigured. If you see the server exit immediately after setting tls_cert/tls_key, check the startup log: it names both paths and the reason the TLS acceptor couldn't be built. Fix the certificate or key and restart.

Requiring TLS for specific hosts​

Combine TLS with a host-based rule to require it only for connections you don't already trust, for example everything outside your private network:

# /etc/scramdb/pg_hba.conf
host    all    all    10.0.0.0/8    trust
hostssl all    all    0.0.0.0/0     password
hostssl all    all    ::/0          password

hostssl matches only a connection already using TLS; hostnossl matches only a connection that is not. A client attempting a plaintext connection against a line that requires hostssl fails to match that rule (and, if no other line matches, is rejected). The full hba_file grammar, including how rules are evaluated, is covered in Authentication.

In Docker​

The Docker deployment guide shows the same tls_cert/tls_key keys mounted from PEM files at /etc/scramdb/server.crt and /etc/scramdb/server.key; use that path convention if you're running the published image.