Security: Authentication, Encryption, and RBAC

OxiDB's TCP server includes enterprise-grade security features: SCRAM-SHA-256 authentication, role-based access control, TLS encryption, and transparent at-rest encryption.

SCRAM-SHA-256 Authentication

OxiDB uses SCRAM-SHA-256 (Salted Challenge Response Authentication Mechanism) — the same protocol used by PostgreSQL and MongoDB. The password is never sent over the wire, even without TLS.

How it works:

Client sends username and a random nonce
Server responds with salt, iteration count, and combined nonce
Client computes a proof using PBKDF2-derived keys
Server verifies the proof and sends its own signature
Client verifies server signature (mutual authentication)

# Client authentication happens automatically
from oxidb import OxiDbClient

db = OxiDbClient("127.0.0.1", 4444,
                 username="myuser",
                 password="mypassword")

Role-Based Access Control (RBAC)

OxiDB supports three roles with increasing privileges:

Role	Permissions
Read	find, find_one, count, aggregate, text_search, get_object
ReadWrite	All Read permissions + insert, update, delete, put_object, create_bucket
Admin	All ReadWrite permissions + create_index, create_user, manage server

# Create users with specific roles (admin only)
db.create_user("reader", "password123", role="Read")
db.create_user("writer", "password456", role="ReadWrite")
db.create_user("admin2", "password789", role="Admin")

TLS Encryption

Enable TLS for encrypted communication between client and server:

# Server-side: set environment variables
export OXIDB_TLS_CERT=/path/to/cert.pem
export OXIDB_TLS_KEY=/path/to/key.pem

# Client-side
db = OxiDbClient("127.0.0.1", 4444, tls=True)

At-Rest Encryption (AES-GCM)

OxiDB supports transparent encryption at the storage layer using AES-GCM. When enabled, all data is encrypted before being written to disk:

# Server-side: set encryption key
export OXIDB_ENCRYPTION_KEY=your-32-byte-hex-key

# All data files are now encrypted transparently
# No client-side changes needed

AES-GCM provides both confidentiality and authenticity — tampered data is detected and rejected.

Audit Logging

OxiDB server can log all operations for security auditing. Audit logs include:

User identity and IP address
Operation type and target collection
Timestamp
Success/failure status

Server Configuration

Configure the server via environment variables:

OXIDB_ADDR=0.0.0.0:4444      # Listen address (default: 127.0.0.1:4444)
OXIDB_DATA=./oxidb_data       # Data directory
OXIDB_POOL_SIZE=4             # Worker thread pool size
OXIDB_IDLE_TIMEOUT=30         # Client idle timeout in seconds (0 = never)

Wire Protocol

OxiDB uses a length-prefixed JSON protocol over TCP with a 16 MiB message size limit. This prevents denial-of-service via oversized messages while allowing large document transfers.