Skip to main content

Rotate encryption keys

Indexlume uses versioned AES-256-GCM envelopes. Preserve APP_HMAC_KEY and SEARCH_KEY_PEPPER while rotating APP_ENCRYPTION_KEY.

  1. Back up PostgreSQL and retain the current key securely.

  2. Stop new API/worker writes and allow active jobs to finish.

  3. Put the new key in APP_ENCRYPTION_KEY and the old key in APP_ENCRYPTION_KEY_PREVIOUS.

  4. Validate without writes:

    pnpm crypto:rotate:check

  5. Rewrap:

    pnpm crypto:rotate

  6. Restart services, test every connector/projection and an existing public search key, then rerun the dry check.

  7. Remove the old encryption key only when every stored record reports alreadyActive.

Search-key hashes cannot be rewrapped because plaintext keys are not retained. Rotate the pepper by supporting the old value temporarily, issuing replacement keys, revoking old keys, then retiring the old pepper.