nself encryption

Manage encryption keys for at-rest data and in-transit TLS across your nSelf deployment.

Quick start

# Check at-rest encryption status
nself encryption at-rest status

# Enable at-rest encryption (generates a new key automatically)
nself encryption at-rest enable

# Verify TLS is working end-to-end
nself encryption in-transit test

Synopsis

nself encryption <SUBCOMMAND> [FLAGS]

nself encryption keys <list|rotate|import|export> [FLAGS]
nself encryption at-rest <status|enable> [FLAGS]
nself encryption in-transit <status|test> [FLAGS]

Description

nself encryption controls two independent encryption planes: at-rest encryption for database columns and stored secrets, and in-transit TLS termination managed by Nginx.

At-rest encryption uses envelope encryption: a data encryption key (DEK) protects individual column values; a key encryption key (KEK) wraps the DEK and is stored separately. Rotating the KEK re-wraps existing DEKs without re-encrypting the data. This keeps rotation fast even on large tables.

In-transit encryption is handled by the Nginx layer. nself ssl provisions the certificates; nself encryption in-transit inspects the live TLS configuration and runs a handshake test against every bound service endpoint.

Subcommands

nself encryption keys list

List all managed encryption keys, their status, and the last rotation date.

nself encryption keys list
# ID        TYPE   STATUS    LAST ROTATED
# kek-01    KEK    active    2026-04-01
# dek-01    DEK    active    2026-04-01
# kek-00    KEK    retired   2026-01-15

nself encryption keys rotate

Rotate the active KEK. Existing DEKs are re-wrapped with the new KEK in a background job. The old KEK is kept in a retired state until all DEKs have been migrated, then marked deleted.

nself encryption keys rotate
# Rotates the KEK and queues DEK re-wrapping
# Use --wait to block until migration completes

nself encryption keys import

Import an externally managed KEK (hex or base64 encoded). Useful for BYOK setups.

nself encryption keys import --from-file ./my-kek.key
nself encryption keys import --hex 4a7f3b...

nself encryption keys export

Export the active KEK for backup or migration. Requires --confirm.

nself encryption keys export --out ./backup-kek.key --confirm

nself encryption at-rest status

Show which Postgres columns are encrypted and their encryption coverage.

nself encryption at-rest status
# TABLE              COLUMN          ENCRYPTED
# np_users           email           yes
# np_users           phone           yes
# np_audit_log       payload         no

nself encryption at-rest enable

Enable at-rest encryption for all supported columns. Generates a new KEK if none exists. Runs a background migration to encrypt existing plaintext rows.

nself encryption at-rest enable
nself encryption at-rest enable --wait   # block until migration done

nself encryption in-transit status

Print the TLS configuration for each Nginx endpoint: certificate expiry, cipher suite, and protocol version.

nself encryption in-transit status
# ENDPOINT                CERT EXPIRY   PROTOCOL   CIPHER
# api.local.nself.org     2027-04-01    TLSv1.3    AES-256-GCM

nself encryption in-transit test

Run a TLS handshake test against all service endpoints and report any failures.

nself encryption in-transit test
# api.local.nself.org   OK (TLSv1.3)
# auth.local.nself.org  OK (TLSv1.3)
# All 6 endpoints passed

Flags

Examples

Enable at-rest encryption on a fresh install

nself encryption at-rest enable --wait
nself encryption at-rest status

BYOK: import your own key encryption key

# Generate a 256-bit key externally
openssl rand -hex 32 > my-kek.hex
nself encryption keys import --hex "$(cat my-kek.hex)"
nself encryption keys list

Rotate keys on a schedule

# Add to cron: rotate KEK monthly
nself encryption keys rotate --wait --json | jq '.new_key_id'

Audit TLS configuration before a production deploy

nself encryption in-transit status --env prod
nself encryption in-transit test --env prod

Export KEK for offsite backup

nself encryption keys export --out /secure/backup/kek-$(date +%F).key --confirm

Environment variables

• NSELF_ENCRYPTION_KEY — seed a KEK from the environment (useful in automated provisioning)
• NSELF_ENV — default environment (local | staging | prod)

Exit codes

• 0 — success
• 1 — generic error
• 2 — invalid arguments
• 4 — TLS test failure (in-transit test only)
• 5 — migration incomplete (rotate/enable without --wait)

Related

• nself ssl — provision and renew TLS certificates
• nself doctor — includes encryption health checks
• nself backup — encrypted backup support