# TLS and authentication

Encryption, authentication, and deployment guidance for ParticleDB endpoints.

Source: https://particledb.ai/connectivity/tls/

This page shows how to encrypt connections with TLS and how clients authenticate on each interface. With a certificate configured, ParticleDB terminates TLS itself on SQL clients, native clients, gRPC, Redis and HTTP. The dedicated health-check port and the Prometheus exporter port stay plain HTTP.

## TLS Configuration

### Server-side TLS

1. **Generate or obtain certificates**

   For a production deployment, use a certificate from your CA. For testing,
   create a local CA and a server certificate signed by it:

   ```bash
   # A local certificate authority
   openssl req -x509 -newkey rsa:4096 -sha256 -days 3650 -nodes \
     -keyout ca.key -out ca.crt -subj "/CN=ParticleDB local CA"

   # A server certificate for localhost, signed by that CA
   openssl req -newkey rsa:4096 -sha256 -nodes \
     -keyout server.key -out server.csr -subj "/CN=localhost"
   printf "subjectAltName=DNS:localhost,IP:127.0.0.1\n" > san.ext
   openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
     -days 365 -sha256 -extfile san.ext -out server.crt
   ```

   Clients verify the server against `ca.crt`. A single self-signed
   certificate used as its own root works with `psql`, but `pdb-cli` and other
   clients with strict verification reject it (*CA used as end entity*), so
   prefer the two-step form above.

2. **Set file permissions**

   ```bash
   chmod 600 server.key ca.key
   chmod 644 server.crt ca.crt
   ```

3. **Start ParticleDB with TLS**

   ```bash
   particledb start \
     --tls-cert /path/to/server.crt \
     --tls-key /path/to/server.key
   ```

   In config files, the server reads TLS paths from the network section:

   ```toml
   [network]
   tls_cert_path = "/path/to/server.crt"
   tls_key_path = "/path/to/server.key"
   ```

Once a certificate is configured, the TCP listeners that use it accept **only**
TLS connections on their configured addresses. A
PostgreSQL client that does not request TLS
(`sslmode=disable`) is refused with SQLSTATE `08004` (*server requires TLS*);
plain-text native client, gRPC, Redis and HTTP connections to those ports fail as
well. Local Unix-socket connections are not affected.

## Client Connections With TLS

```bash
# Encrypted, server not verified
psql "postgresql://postgres@localhost:5432/particledb?sslmode=require"

# Encrypted and verified against your CA (host name must match the certificate)
psql "postgresql://postgres@localhost:5432/particledb?sslmode=verify-full&sslrootcert=ca.crt"

# Native wire
pdb-cli -h localhost -U postgres --sslmode verify-full --sslrootcert ca.crt
```

`\conninfo` in `psql` shows the negotiated protocol, for example
`SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, …)`.

```python
import psycopg2

conn = psycopg2.connect(
    host="localhost",
    port=5432,
    dbname="particledb",
    user="postgres",
    password="secret",
    sslmode="verify-full",
    sslrootcert="/path/to/ca.crt",
)
```

## Authentication

Authentication is on by default. The same users and passwords apply to every
protocol; `--auth-method` chooses how SQL client clients prove their
password:

| Method | Description |
|--------|-------------|
| `scram-sha-256` | Recommended; safe with or without TLS |
| `password` *(default)* | Cleartext password exchange; requires TLS. refused over a non-TLS connection |
| `trust` | No password on any protocol. local development only |
| `md5` | Disabled unless you also pass `--allow-md5-auth`; legacy clients only |

```bash
particledb start --auth-method scram-sha-256 --pg-password-file /etc/particledb/pg_password
```

`--pg-password` / `--pg-password-file` set the password of the initial superuser
(`postgres` unless you change it with `--pg-username`). Create further users
with `CREATE ROLE … LOGIN PASSWORD …`.

## Per-Protocol Notes

### SQL clients

- Direct TLS supported
- Auth: `scram-sha-256`, `password`, `trust` (and `md5` with `--allow-md5-auth`)

### gRPC

- Direct TLS supported
- When authentication is on, send HTTP Basic credentials in the `authorization`
  metadata: `Basic `. A
  `Bearer :` header is not accepted. `Health` needs no credentials.

Example:

```bash
grpcurl \
  -cacert ca.crt \
  -H "authorization: Basic $(printf 'postgres:secret' | base64)" \
  -proto particledb.proto \
  -d '{}' \
  localhost:7173 \
  particledb.v1.ParticleDB/Health
```

### HTTP API

- With `--tls-cert` / `--tls-key`, the main HTTP port serves HTTPS only
  (`curl --cacert ca.crt https://localhost:7173/health`). The dedicated
  health-check port and the Prometheus exporter stay plain HTTP.
- When authentication is on, `/v1/*` endpoints (except `/v1/version`) require
  HTTP Basic credentials; `/metrics` on the HTTP port requires a superuser.
- `--require-tls-for-credentials` refuses HTTP Basic credentials sent over a
  non-TLS connection (`401`, *credentials require TLS*).
- A reverse proxy or ingress in front of the HTTP port works as well:

```text
client -> https://db.example.com -> reverse proxy -> http://127.0.0.1:7173
```

### Native clients

- Direct TLS supported, with the same certificate
- Authenticates against the same users; `pdb-cli` takes `--sslmode`,
  `--sslrootcert`, `--sslcert` and `--sslkey`

### Redis clients

- Direct TLS supported
- Authenticate with `AUTH  ` (the single-argument
  `AUTH ` form authenticates as a user named `default`)

```bash
redis-cli -p 6379 --tls --cacert ca.crt --user postgres --pass mysecretpassword
```

## Security Best Practices

1. Enable TLS in production for the SQL and native clients, gRPC, Redis, and HTTP.
2. Do not use `trust` outside local development.
3. Front the built-in HTTP server with your normal reverse proxy if you need rate limiting or WAF behavior.
4. Bind listeners to specific interfaces when possible.
5. Use Unix sockets for local PG connections when you want the lowest-overhead path; restrict them with `--unix-socket-mode 0700` or `--unix-socket-require-same-uid`.
6. Enable audit logging if you need an in-database activity trail:

   ```bash
   particledb start --audit-log
   ```

   Each statement is recorded with its user, client address, operation, target
   and SQL text. Read it with `SELECT * FROM __pdb_audit_log`. Add
   `--audit-log-selects` to record `SELECT` statements too.

## Next Steps

- [Configuration](/installation/configuration/). Full server configuration reference
- [SQL client compatibility](/connectivity/pg-wire/). Client compatibility and auth behavior
- [Connectivity Overview](/connectivity/overview/). Client addresses and authentication

## Related

[Documentation home](/docs/) · [Troubleshooting](/guides/troubleshooting/)
