OpenSSL and TLS

TulaDB release builds always include OpenSSL. It provides three things:

	What	Notes
Native TLS	every listener: client, query, fabric (replication) and heartbeat	TLS 1.2 is the minimum; nodes verify each other’s certificates and their address or hostname
Mutual TLS	client certificates on those listeners	mandatory on a cluster, because the fabric port grants cluster administration
Storage encryption (opt-in)	WAL frames, transaction segments, account metadata and checkpoints, snapshots, the partition index	AES-256-CTR with an HMAC-SHA256 tag over each record (encrypt-then-MAC); off by default

Hashing that is part of the data model, such as the SHA3-256 transfer identity, does not depend on OpenSSL and is the same on every platform.

Which OpenSSL

Platform	OpenSSL	Where it comes from
Ubuntu 22.04, 24.04	3.0.x	the distribution’s libssl3 (libssl3t64 on 24.04), installed with the package
Debian 12	3.0.x	the distribution’s libssl3
RHEL 9 family	3.x	the distribution’s openssl-libs
macOS (development)	3.x	Homebrew: brew install openssl@3 before installing

On Linux, TulaDB links the system OpenSSL. It does not ship its own copy, so an OpenSSL security fix is a normal OS update. A running node keeps the library it loaded at start, so restart it after the update:

sudo apt-get update && sudo apt-get install --only-upgrade libssl3    # or: sudo dnf upgrade openssl-libs
sudo systemctl restart tuladbd                                      # one node at a time in a cluster

To check which library a running node has loaded:

sudo grep -m1 libssl /proc/$(systemctl show -p MainPID --value tuladbd)/maps | awk '{print $6}'

On macOS, the development build loads Homebrew’s OpenSSL 3. Without it, the installer stops and names the fix: brew install openssl@3.

TLS on a single node

A single node installed by tuladb-installer listens on 127.0.0.1 only. It authenticates clients with API keys and needs no TLS. Turn TLS on when clients connect from elsewhere: bind node_addr to the address they use, and set:

network_tls_enabled  = 1
network_tls_cert_file = "/etc/tuladb-pki/node.crt"
network_tls_key_file  = "/etc/tuladb-pki/node.key"
network_tls_ca_file   = "/etc/tuladb-pki/ca.crt"
security_allow_non_loopback_bind = 1

A node reachable beyond loopback must run mutual TLS (network_mtls_required = 1). The engine refuses to start otherwise: the fabric listener binds the same address and grants cluster administration.

Mutual TLS in a cluster

tuladb-installer install --cluster-node sets this up from --tls-cert, --tls-key and --tls-ca. Each node needs:

• a certificate signed by the cluster’s CA, with a SAN for the address its peers use;
• both serverAuth and clientAuth extended key usages (a node is a server to clients and a client to its peers);
• a key readable by the tuladb group: mode 0640, group tuladb.

Install TulaDB has the commands to make them.

Clients connect with TLS and their own certificate:

tulactl --host 10.0.0.1 --tls --tls-ca-file ca.crt \
  --tls-cert-file client.crt --tls-key-file client.key \
  --api-key "$KEY" ready

A client certificate proves the connection is allowed. What the client may do is set by roles: an API key’s principal, or the certificate’s identity when network_require_authenticated_clients = 1 (see Security).

Rotating and revoking certificates

• Expiry. The certificate loaded at start is reported as tuladb_tls_cert_days_remaining in Prometheus. Alert well before it reaches zero.

• Rotation. Replace the files and restart the node. In a cluster, do one node at a time and wait until tuladb-installer status shows it ready before the next. A new certificate must chain to the CA the other nodes trust, and should keep the same principal (the first spiffe:// URI SAN, else the first urn:, else the first URI, else the first DNS SAN, else the first subject CN): node.toml grants that principal read-only for the installer’s own status probe, so a new principal needs its role_grant_1 updated too. To rotate the CA itself, first put a bundle with both the old and the new CA in network_tls_ca_file on every node.

• Revocation. Set network_tls_crl_file to a PEM CRL. SIGHUP reloads it on every listener without a restart:

  openssl ca -gencrl -out /etc/tuladb-pki/crl.pem
  sudo systemctl kill -s HUP tuladbd

  A CRL that fails to parse on reload is reported (tls_crl_reload_failed) and the previous one stays installed. A CRL that cannot be read at start stops the node from starting.

Storage encryption

Off by default. To encrypt the store at rest, give the node a 256-bit key from a file only the service can read, before the first start:

openssl rand -hex 32 | sudo install -m 0400 -o tuladb -g tuladb /dev/stdin /etc/tuladb-pki/storage.key

storage_encryption_enabled  = 1
storage_encryption_key_file = "/etc/tuladb-pki/storage.key"

Keep the key with your secrets. The data cannot be read without it, and backups need the same key to restore. A node that holds any secret material (a storage key, a TLS key, an API key file) makes itself non-dumpable at start, so a crash never writes a key into a core file. The keys are described in Configuration.