Keys & custody

Keep access credentials separate from the authority that unlocks storage.

On this page

Encryption is an instance choice

At-rest encryption is optional and disabled by default for newly created databases. Select --encryption-at-rest on when initializing either native or external custody. Plaintext storage still needs the configured integrity key before data operations can begin.

The authenticated instance configuration binds its protection mode to the wrapped key. Existing files keep their mode; verified mode conversion and complete key rotation remain development work.

Native recovery

Native initialization creates a random storage key and wraps it using a key derived from a recovery passphrase with Argon2id. The passphrase is entered privately. The owner credential authenticates API access; it is not the encryption key.

The current passphrase flow is not a threshold ceremony. Full native ceremonies, role assignment, rotation, revocation and independent key lifecycle acceptance remain open. No completed post-quantum custody protocol is claimed.

Explicit external providers

The Linux local provider socket must be absolute, private and owned by the pinned UID. Peer credentials authenticate the broker. Its length-prefixed JSON exchange binds protocol version, provider, instance, purpose, fresh nonce and short-lived release. The complete exchange has a deadline.

The broker supplies an instance-scoped wrapping key to recovery, never an authority-wide master seed. Provider unavailability or wrong identity fails closed. External mode cannot fall back to a native passphrase. The browser never receives a storage key.

bash

qiravad init --data /private/qirava-data \
  --provider-socket /private/provider.sock \
  --provider-id my-provider --provider-uid 1000

Key memory and recovery boundaries

Key holders zeroize retained key material when dropped. The host still owns process isolation, swap, core dumps and source key copies. Do not equate zeroization with locked memory or protection from the process owner.

Recovering keys must not depend on opening the encrypted business database. A matching rollback of every authenticated local file requires independent freshness evidence to detect. Encryption alone cannot detect that rollback.