Skip to content

Key custody and trust domains

Masterplan keeps four cryptographic trust domains separate. A signature proves that one key signed one exact digest. It does not prove legal compliance or physical deletion outside controlled systems.

Trust domain Generation and owner Storage and recipients Backup, rotation, revocation and recovery
Server instance Generated exactly once by the management TUI after explicit commissioning confirmation. Owned by the deployment Private key in the protected Server secret area. Public key and fingerprint in the instance trust record. HA nodes share the same key through encrypted secret replication Private key occurs only in encrypted, verified Server recovery packages. Missing or mismatched material fails closed. Planned rotation creates continuity before retirement and switches all HA nodes consistently
Root passkey Generated and retained by Windows Hello, a hardware security key or another WebAuthn authenticator Authenticator private key never enters Server. Server holds WebAuthn public credential data and verification records only Register a replacement first where possible. Lost-root recovery uses the guarded root workflow and revokes affected sessions. Challenges are exact-action bound, short-lived and single-use
Controller Generated on a controller-controlled workstation or hardware device through the separate controller-custody utility Private key stays under controller control. The setup download is unencrypted so it can be placed directly in a password manager or other protected store, then deleted from Downloads. Server receives public material, proof of possession and signed declarations only Use a protected password-manager or offline recovery copy, or additional controller-key continuity. Routine rotation requires old and new proof. Loss or compromise requires root passkey authorisation and an explicit continuity record
Processor Generated by Masterplan Desktop or imported from the client-only Evidence-Public generator The encrypted import is decrypted in memory and copied into the operating-system credential store. Server receives public material and signed Desktop evidence only Each identity is immutably assigned to one event. Routine rotation requires continuity proof. Loss or compromise requires root passkey authorisation; old public keys remain for verification

The typed roles are instance, root_passkey, controller and processor. Root is a technical privileged role and is not automatically the legal controller. If one organisation performs controller and processor work, it still uses separate entity identifiers, keys and signed role statements.

Registration sequence

  1. Commission Server and create the instance key once.
  2. Bootstrap root and register its passkey.
  3. In the restricted setup wizard, generate the controller key locally or import a compatible private package, then download and re-import it to verify recovery before registration.
  4. Root creates a short-lived Server challenge bound to controller ID, instance ID, role, fingerprint, exact action, expiry and nonce.
  5. The external controller key proves possession. Root then completes a separate WebAuthn ceremony for that exact action.
  6. The instance key signs the durable ledger record. It distinguishes external proof, root passkey authorisation, Server verification and instance signing.
  7. Successful proof plus exact root authorisation establishes controller trust for governance authority. No separate trust declaration is required.
  8. Complete and publish governance version 1 in the setup wizard. Automatic final checks append the commissioning receipt before administration opens.
  9. Link an event from Desktop. Desktop generates a new event processor key or imports an encrypted package, signs the event-bound challenge automatically, and waits for root approval in Governance > Trust & keys.

The API rejects unknown or private-key fields, wrong-role proof, entity or instance substitution, changed action digests, expiry, replay, activation before proof and activation without root WebAuthn.

Controller workstation utility

Run this only from trusted source on a controller-controlled workstation:

python tools/controller_custody.py generate --controller-id ctl-example0001 --output-dir /protected/controller-custody
python tools/controller_custody.py sign --private-key /protected/controller-custody/ek-....controller.ed25519.pem --document challenge.json --output proof.json
python tools/controller_custody.py verify-recovery --private-key /protected/recovery/ek-....pem --public-package ek-....controller.public.json

The software fallback creates an unencrypted private PEM with owner-only permissions. Move it immediately into a password manager, hardware-backed store or protected offline custody and remove the transient working copy. The utility signs the versioned controller governance-authority registration challenge only. It rejects processor statements and obsolete trust-declaration formats.

Desktop processor workflow

Desktop must enrol an event processor before permitted-data acknowledgement or publishing. It can generate a key locally or import the encrypted mp-opt-processor-private-key-v1.json format. It signs event registration, permitted-data acknowledgement, Desktop deletion receipts, work-order claims, and local-copy resolutions automatically. It cannot sign Server deletion, Server backups, controller governance or final case closure. Ordinary UI, exports, logs and diagnostics never expose private processor bytes.

Only synthetic identities and keys are used by automated tests. Real ceremonies require a later manual gate. Historical public keys and verification records are retained after rotation or revocation so old signatures remain verifiable.