TLS / Security

ParticleDB supports TLS encryption and password authentication across all protocols. This guide covers certificate setup, authentication configuration, and security best practices.

TLS Configuration

Server-side TLS

1. Generate or obtain certificates

   For development, generate a self-signed certificate:

   openssl req -x509 -newkey rsa:4096 -sha256 -days 365 \
     -nodes -keyout server.key -out server.crt \
     -subj "/CN=particledb" \
     -addext "subjectAltName=DNS:localhost,IP:127.0.0.1"

   For production, use certificates from a trusted CA (Let’s Encrypt, your internal PKI, etc.).

2. Set file permissions

   chmod 600 server.key
   chmod 644 server.crt

3. Start ParticleDB with TLS

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

   Or in config.toml:

   [security]
   tls_cert_path = "/path/to/server.crt"
   tls_key_path = "/path/to/server.key"

Client connections with TLS

Once TLS is enabled on the server, clients connect with SSL:

# psql
psql "postgresql://localhost:5432/main?sslmode=require"

# Verify server certificate
psql "postgresql://localhost:5432/main?sslmode=verify-full&sslrootcert=ca.crt"

# psycopg2
import psycopg2
conn = psycopg2.connect(
    host="localhost",
    port=5432,
    dbname="main",
    sslmode="require",
    sslrootcert="/path/to/ca.crt",  # optional: verify server cert
)

// node-postgres
import { Client } from "pg";
import fs from "fs";

const client = new Client({
  host: "localhost",
  port: 5432,
  database: "main",
  ssl: {
    rejectUnauthorized: true,
    ca: fs.readFileSync("/path/to/ca.crt").toString(),
  },
});

// pgx
config, _ := pgx.ParseConfig("postgresql://localhost:5432/main?sslmode=require")
conn, _ := pgx.ConnectConfig(ctx, config)

// JDBC
String url = "jdbc:postgresql://localhost:5432/main?ssl=true&sslmode=require";
Connection conn = DriverManager.getConnection(url);

// Npgsql
var connString = "Host=localhost;Port=5432;Database=main;SSL Mode=Require;Trust Server Certificate=true";
await using var conn = new NpgsqlConnection(connString);

SSL Modes

Mode	Server Cert Verified	Encryption	Use Case
disable	No	No	Development only
allow	No	If available	Legacy compatibility
prefer	No	If available	Default for most drivers
require	No	Yes	Production minimum
verify-ca	CA only	Yes	Trusted CA environments
verify-full	CA + hostname	Yes	Production recommended

Authentication

Auth methods

ParticleDB supports three authentication methods for the PostgreSQL wire protocol:

Method	Security	Description
trust	None	All connections accepted without password (default)
password	Low	Cleartext password — use only with TLS
md5	Medium	MD5-hashed password challenge

Configuring authentication

# Start with password auth
particledb start \
  --auth-method password \
  --pg-password mysecretpassword

# Start with MD5 auth
particledb start \
  --auth-method md5 \
  --pg-password mysecretpassword

Or in config.toml:

[security]
auth_method = "password"
pg_password = "mysecretpassword"

Or via environment variable:

PDB_AUTH_METHOD=password
PDB_PG_PASSWORD=mysecretpassword

Connecting with authentication

# psql (will prompt for password)
psql -h localhost -p 5432 -U admin -d main

# psql with password in connection string
psql "postgresql://admin:mysecretpassword@localhost:5432/main"

conn = psycopg2.connect(
    host="localhost",
    port=5432,
    dbname="main",
    user="admin",
    password="mysecretpassword",
)

Per-Protocol Security

PostgreSQL Wire Protocol (port 5432)

• TLS: Enabled via --tls-cert and --tls-key
• Auth: trust, password, or md5 via --auth-method
• Recommendation: Use --auth-method md5 with --tls-cert and --tls-key for production

gRPC (port 26257)

• TLS: Same certificates as PG wire (applied server-wide)
• Auth: Token-based via authorization metadata header

grpcurl -cacert ca.crt \
  -H "authorization: Bearer <token>" \
  localhost:26257 particledb.Admin/GetStatus

HTTP API (port 8080)

• TLS: Same certificates as PG wire
• Auth: Bearer token or HTTP Basic auth

curl -X POST https://localhost:8080/query \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT 1"}'

Redis RESP (port 6379)

• TLS: Same certificates as PG wire
• Auth: Redis AUTH command

redis-cli -p 6379 --tls --cacert ca.crt
AUTH mysecretpassword

Security Best Practices

1. Always enable TLS in production. Without TLS, passwords and query data are sent in cleartext.

2. Never use trust authentication in production. It allows any connection without a password.

3. Never use password (cleartext) auth without TLS. Use md5 if you cannot enable TLS.

4. Restrict network access. Bind to specific interfaces instead of 0.0.0.0:

   particledb start --pg-addr 10.0.1.5:5432

5. Use Unix sockets for local connections. They bypass the network stack entirely and are secured by filesystem permissions:

   particledb start --pg-unix-socket /var/run/particledb/.s.PGSQL.5432
   chmod 700 /var/run/particledb/

6. Rotate certificates regularly. Set up automated certificate renewal with your CA.

7. Use strong passwords. At least 16 characters with mixed case, numbers, and symbols.

8. Monitor audit logs. Enable audit logging to track access:

   particledb start --audit-log true

Next Steps

• Configuration — Full server configuration reference
• PostgreSQL Wire Protocol — Protocol details and client compatibility
• Connectivity Overview — All protocols and ports