Skip to content

TLS

namidb-server terminates TLS itself (rustls, TLS 1.2 and 1.3). Pass a PEM certificate chain and its private key; both listeners, HTTP and Bolt, then require TLS.

Terminal window
namidb-server \
--store "file:///var/lib/namidb?ns=prod" \
--auth-tokens-file /etc/namidb/tokens.json \
--listen 0.0.0.0:8443 \
--bolt-listen 0.0.0.0:7687 \
--tls-cert /etc/namidb/tls/fullchain.pem \
--tls-key /etc/namidb/tls/privkey.pem
FlagEnv varMeaning
--tls-certNAMIDB_TLS_CERTPEM certificate chain (leaf first).
--tls-keyNAMIDB_TLS_KEYPEM private key for the leaf certificate.

Set both or neither. Without them the server speaks plaintext; in that case terminate TLS in front of it (a reverse proxy, a load balancer or a service mesh) and keep the plaintext port on a private network.

Clients

Terminal window
curl -s --cacert ca.pem https://namidb.internal:8443/v0/health
Bolt URLUse when
bolt+s://host:7687The certificate chains to a CA the client trusts.
bolt+ssc://host:7687Self-signed or private-CA certificate (encryption without verification).
bolt://host:7687Plaintext only. Against a TLS listener it fails.
from neo4j import GraphDatabase
driver = GraphDatabase.driver("bolt+s://namidb.internal:7687", auth=("namidb", token))

A test certificate

Terminal window
openssl req -x509 -newkey rsa:2048 -nodes -keyout key.pem -out cert.pem -days 30 \
-subj "/CN=localhost" -addext "subjectAltName=DNS:localhost,IP:127.0.0.1"
namidb-server --store memory://tls --auth-token "$NAMIDB_AUTH_TOKEN" \
--listen 127.0.0.1:8443 --bolt-listen 127.0.0.1:7687 \
--tls-cert cert.pem --tls-key key.pem
curl -s --cacert cert.pem https://localhost:8443/v0/health

Docker

Mount the certificate files and set them through the environment so the image’s built-in health check notices TLS and probes over HTTPS:

Terminal window
docker run -d -p 8443:8443 \
-v /etc/namidb/tls:/tls:ro \
-e NAMIDB_LISTEN=0.0.0.0:8443 \
-e NAMIDB_TLS_CERT=/tls/fullchain.pem \
-e NAMIDB_TLS_KEY=/tls/privkey.pem \
-e NAMIDB_AUTH_TOKEN \
namidb/namidb-server:3.3.0 --store memory://demo

The health check reads NAMIDB_LISTEN, NAMIDB_TLS_CERT and NAMIDB_TLS_KEY. If you set the listen address or TLS with command-line flags instead, mirror them in these variables or replace the health check in your orchestrator. The probe skips certificate verification for its own loopback request, since deployment certificates rarely include loopback addresses.

Certificate rotation

The certificate and key are read at startup. To rotate, replace the files and restart the server; plan the restart like any other (one server per namespace, see Multi-tenant mode).

Outbound connections

Connections from the server to object stores, a JWKS endpoint or a policy endpoint use HTTPS according to their URLs. Plain HTTP to an S3-compatible endpoint must be allowed explicitly with allow_http=true in the storage URI.