Skip to content

Activating Encryption

Activation is a short guided ceremony. It generates the master key, shows it to you once, and refuses to proceed until you prove you saved it. Interrupting it at any point breaks nothing.

Before you start

  1. The key holder must be running. mpy-masterkeyd is the small process that holds the master key in memory. On a provisioned server it runs as a service; on a development box, start it with:
make masterkeyd-run

If the default runtime directory is not writable on your machine, the error message hands you the exact line to run instead (typically make masterkeyd-run MASTERKEYD_DIR=/dev/shm/mpy-masterkeyd). The daemon starts empty and announces its socket; Muppy finds it by itself — nothing to configure.

!!! note "To be completed: LXC and Kubernetes deployments"
    Setting up the key holder per deployment target will be documented here:
    on an **LXC / bare-metal** server, as the systemd service declared in
    `.muppy/services.yml`; on **Kubernetes**, as a dedicated pod (planned — the
    daemon and its protocol are ready for it, the manifests are not shipped yet).

  1. Have your password manager open. The ceremony will give you two things to paste into it, and the whole design assumes they end up there.

  2. You need to be a member of the Vault Encryption Administrator group to see the screen.

The ceremony

Open Vault ▸ Encryption. On a database where encryption was never activated, the screen shows state Not created and offers a single action: Generate the master key. The Encryption screen before activation

  1. Generate. The wizard displays the new master key once, with a copy button, and a suggested password-manager entry name of the form mpy-masterkey@<your-server-url> — also copiable. Save both in your password manager now.

The generation ceremony: the key shown once, and the paste-back

!!! warning "It will never be shown again"
    The key is displayed at this moment and at no other. Muppy stores no copy —
    that is the entire point. If you lose it, nothing encrypted under it can ever
    be read again.

  1. Type it back. The wizard asks you to paste the key again. This is not bureaucracy: it proves the key actually reached your password manager before anything depends on it. A wrong paste-back refuses, and nothing has been installed.

  2. Activate encryption. On confirmation Muppy hands the key to the holder, creates the first data key, wraps the keyring and proves the envelope opens. The screen turns Unsealed, and the chatter records who activated, when, and under which key identifier.

The screen after activation: unsealed, one envelope, one data key

Check it worked

  • Click Run self-test on the Encryption screen. It runs five non-destructive checks (holder reachable, envelope opens, a full encrypt/decrypt round-trip through the store, key coverage, no orphans) and prints a readable verdict. This button is always safe — it is the right reflex whenever you are in doubt.
  • From now on, every new write of a declared secret field is encrypted immediately. You can see it in the Coverage tab: encrypted counts rise as secrets are written.

What activation does not do

Activation encrypts new writes. Secrets that already existed before activation stay in clear in their original columns until you run the sweep ("Encrypt secrets still in clear") — and the sweep is a decision, not an automatism, because clearing the plaintext is the point of no return.

Do not run the sweep on a production database without reading Trial and Production first. The deployment trial lets you sweep without destroying the plaintext, run for weeks with a safety net, and only commit once you have certified the vault against your own data.