Encryption

Goal

Configure data-at-rest protection with TDE and understand the server-side contract for client-encrypted columns.

Prerequisites

Access to server environment variables or configuration file.
A 256-bit master key (64 hex characters) for TDE.
Ability to restart the server after TDE changes.

TDE — Transparent Data Encryption (v0)

TDE encrypts data at rest without application changes. When enabled, the following are encrypted:

Storage pages (the .adb data file).
WAL (write-ahead log) entries.
Audit sink on disk (JSONL trail).

Configure TDE

export ANGARABASE_TDE_ENABLE=1
export ANGARABASE_TDE_MASTER_KEY_HEX=<64-hex-characters>
export ANGARABASE_TDE_MASTER_KEY_ID=master-prod-2026q1
export ANGARABASE_TDE_LAST_ROTATION_UNIX=1760000000

Variable	Purpose
`ANGARABASE_TDE_ENABLE`	`1` to enable; unset or `0` to disable.
`ANGARABASE_TDE_MASTER_KEY_HEX`	256-bit key in hex (64 characters). Never appears in `sys.settings` or logs.
`ANGARABASE_TDE_MASTER_KEY_ID`	Human-readable, non-secret key identifier (visible in `sys.settings`).
`ANGARABASE_TDE_LAST_ROTATION_UNIX`	Unix timestamp of the last key rotation (metadata only).

Fail-closed behaviour

If ANGARABASE_TDE_ENABLE=1 and the key is missing, malformed, or wrong length, the server refuses to start.
If the key is invalid for the existing data directory, page/WAL decryption fails at startup — also fail-closed.
The audit sink follows the same rule: without a valid key, audit read/write is impossible.

Verify from SQL

SELECT name, value
FROM sys.settings
WHERE name IN (
 'security.tde_enabled',
 'security.tde_master_key_id'
)
ORDER BY name;

Only non-secret metadata (key_id, enabled flag) is exposed. The hex key itself never appears.

Client-encrypted columns

Client-encrypted columns allow applications to store ciphertext in the database while the server never holds key material.

SQL surface

ALTER TABLE customers
 ALTER COLUMN tax_id
 SET ENCRYPTED WITH (TYPE=DETERMINISTIC, KEY_ID='cust-key-01');

Full syntax:

ALTER TABLE <table>
 ALTER COLUMN <column>
 SET ENCRYPTED WITH (
 TYPE = DETERMINISTIC | RANDOMIZED,
 KEY_ID = '<opaque-id>',
 ALG = '<algorithm-id>' -- optional, defaults to AES-256-SIV / AES-256-GCM
 );

What the server stores

Field	Content
`enc.alg`	Algorithm identifier (whitelisted).
`enc.mode`	`deterministic` or `randomized`.
`enc.key_id`	Opaque, non-secret key identifier.
payload	Ciphertext bytes — never interpreted by the server.

The server never accepts raw key material via SQL, environment variables, config, logs, or sys.* views.

Operator rules

Mode	Allowed operations	Rejected operations
`DETERMINISTIC`	Equality predicates (`=`, `!=`, `IN`)	Range, LIKE, aggregation, ordering
`RANDOMIZED`	None (read/write only)	All server-side predicates

Unsupported operations return 0A000 feature_not_supported (shape-stable error).

Fail-closed and observability

Missing or invalid encryption metadata on a column causes DML to be rejected.
sys.settings and diagnostics expose only key_id, mode, and algorithm — never ciphertext blobs or key-like material.
Error messages never include ciphertext fragments or key material.

Expected result

With TDE enabled, the data directory contains no plaintext data, WAL, or audit payloads.
sys.settings shows security.tde_enabled = true and the key_id without exposing the key.
Client-encrypted columns store ciphertext; deterministic mode allows equality queries; randomized mode rejects server-side predicates.
All fail-closed paths produce deterministic errors, not silent fallbacks.

Troubleshooting

Server refuses to start after enabling TDE Check ANGARABASE_TDE_MASTER_KEY_HEX — must be exactly 64 hex characters. If the data directory was previously unencrypted, you cannot enable TDE retroactively on existing data (see migration docs).
0A000 feature_not_supported on encrypted column query The query uses an unsupported operator for the column’s encryption mode. For RANDOMIZED columns, only read/write is allowed. For DETERMINISTIC, only equality predicates work.
Audit read/write fails with TDE enabled The audit DEK derives from the master key. Verify the master key matches the one used when the audit file was created.
sys.settings does not show TDE knobs Ensure ANGARABASE_TDE_ENABLE=1 is set in the environment before server startup.
Need a bug-report artifact? See ../reference/support.md.

AngaraBook