Virtual Signer disaster recovery

Generate the recovery key pair, configure it, and recover vaults from Virtual Signer .dr files

A Virtual Signer is an unattended, server-side signer. Unlike a Mobile Signer, it has no owner holding a backup file and no secret phrase to write down. Instead, it writes its own encrypted disaster recovery files (.dr files), which only your organisation's private key can open.

Each time the Virtual Signer takes part in a key generation or a reshare, it encrypts its share material to a public key that you supply and writes the result to disk. The matching private key never touches the Virtual Signer. It stays offline with your organisation, and it's the only thing that can decrypt those files later.

The most important step therefore happens before you start the Virtual Signer for the first time.

❗️

The recovery key pair must exist before first start

The Virtual Signer doesn't start without a disaster recovery public key, and it seals that key into its configuration when it first registers. There is no supported procedure to change it afterwards.

If you lose the private key, you can never decrypt any .dr file that Virtual Signer has written or will write. Generate the key pair first, verify it, and back it up offline.

Who does what

RoleResponsibility
Product Owner (Business User)Generates the ML-KEM-768 key pair. Stores the private key offline and safely. Verifies that the deployed Virtual Signer uses the matching public key, and that it starts successfully.
IT/DevOps EngineerPlaces the public key PEM file on the Broker host and points IOSIGN_SIGNER_BROKER_DR_PK_PEM_FILE at it. Configures the backup volume. Exports recovery bundles regularly. Never handles the private key.
Recovery operatorDuring a recovery only: runs the disaster recovery tool on an air-gapped machine with the private key and the collected bundles. Gains full access to the recovered vault keys, so choose this person with care.

The split matters. The IT/DevOps Engineer needs only the public key to run the service. Anyone holding the private key can decrypt every Virtual Signer share it protects, so never store it on, or make it reachable from, the machine running the Virtual Signer.

Step 1 — Generate the recovery key pair

Owner: Product Owner (Business User). Do this before you deploy the Virtual Signer.

The key generation script ships with the io.finnet disaster recovery tool. It needs OpenSSL 3.5.0 or later, the first release with ML-KEM support. Check your version with openssl version. The openssl bundled with Git for Windows is often older than 3.5, and the script stops with an error if your build can't generate ML-KEM-768 keys.

Run the script on a secure workstation, preferably offline, and not on the Virtual Signer host.

# macOS / Linux
./scripts/posix/gen_mlkem768.sh
# Windows
.\scripts\windows\gen_mlkem768.ps1

Both scripts accept an optional base name, which defaults to mlkem768:

./scripts/posix/gen_mlkem768.sh treasury-signer

The script produces two files:

FileContentsWho holds it
mlkem768_priv.pemML-KEM-768 private key (PKCS#8), written with file mode 600.The Product Owner, offline. Never goes on the Virtual Signer.
mlkem768_pub.pemML-KEM-768 public key (X.509 SubjectPublicKeyInfo).The IT/DevOps Engineer, for deployment.

The script refuses to overwrite an existing key pair, so it can't destroy a key you already use.

Store the private key

Treat mlkem768_priv.pem with the same care as a Mobile Signer's secret phrase. It plays the same role: it's the one secret that makes recovery possible.

  • Store it offline, on encrypted media, in a physically secure location.
  • Keep more than one copy, in separate locations, so that a single fire or failed drive can't destroy it.
  • Don't store it on the Virtual Signer host, in the deployment repository, in a CI secret store, or anywhere the running service can reach it.
  • Record who holds it and how to retrieve it during an incident. A key nobody can find during an outage is no better than a lost one.

Step 2 — Configure the public key on the Virtual Signer

Owner: IT/DevOps Engineer.

Copy only mlkem768_pub.pem to the Broker host, and point the Broker at it:

ConfigurationDescription
IOSIGN_SIGNER_BROKER_DR_PK_PEM_FILEPath to the ML-KEM-768 public key PEM file used to encrypt disaster recovery files. Required: the Broker doesn't start without it.

Only the Broker needs this setting. MPC Core doesn't need a copy of the key.

A Docker Compose deployment mounts the key and sets the variable:

services:
  vs-broker:
    environment:
      IOSIGN_SIGNER_BROKER_DR_PK_PEM_FILE: /run/signer/mlkem768_pub.pem
    volumes:
      - ./secrets/mlkem768_pub.pem:/run/signer/mlkem768_pub.pem:ro

Start-up validation

If the variable is missing, the Broker exits immediately with:

CONFIG_REQUIRED_MISSING: env var IOSIGN_SIGNER_BROKER_DR_PK_PEM_FILE is required

If the Broker can't read the path, or the file isn't a valid PEM block, it exits with:

CONFIG_INVALID_PEM_FILE: env var IOSIGN_SIGNER_BROKER_DR_PK_PEM_FILE must point to a readable file containing a valid PEM block
🚧

A valid PEM file isn't necessarily the right key

Start-up validation checks only that the file contains a well-formed PEM block. It doesn't check that the key is the ML-KEM-768 public key you intended.

A Virtual Signer configured with the wrong PEM file starts normally, then fails every key generation and reshare with invalid disaster recovery public key. A Virtual Signer configured with a valid but wrong ML-KEM-768 key runs normally and writes .dr files that your private key can't open. You would only find out during a recovery.

Always complete Step 3.

Step 3 — Verify the key and the first start

Owner: Product Owner (Business User).

Before you give the Virtual Signer production signing weight, confirm two things independently of whoever deployed it.

Confirm the deployed public key is yours

Compare a checksum of the key in your own custody with the one the running container uses:

# On your own machine, against your copy
sha256sum mlkem768_pub.pem

# Against the deployed Virtual Signer
docker compose exec vs-broker \
  sh -c 'sha256sum "$IOSIGN_SIGNER_BROKER_DR_PK_PEM_FILE"'

The two digests must match. If they don't, stop and resolve the difference before the signer joins any vault. Your private key can't recover any .dr file written in the meantime.

Confirm the Virtual Signer starts successfully

Check that the Broker reaches a healthy state with that key in place:

docker compose logs vs-broker | tail -50
curl --fail-with-body 'http://127.0.0.1:8182/broker/v1/health?strict=true'

A successful first start with the correct key seals the configuration, as described next.

Immutable configuration

When a Virtual Signer registers for the first time, it seals these settings:

  • The approval mode.
  • The external approval policy base URL.
  • The disaster recovery public key.
  • Whether the Broker's connection to MPC Core is secured.

If any of them changes, the Virtual Signer refuses to start and logs:

IMMUTABLE_CONFIG_MISMATCH - invalid configuration hash or signature - rollback configuration to its original values

This stops anyone, including someone with access to the deployment pipeline, from quietly substituting a different disaster recovery public key. A substituted key would redirect all future .dr files to a key your organisation doesn't hold. Once the Product Owner has verified the key and seen the signer start, that key is pinned for the life of the registration.

You can't change the disaster recovery public key on an existing Virtual Signer. Plan the key pair as a long-lived asset, and verify it before the signer joins production vaults. If the key must change, deploy a new Virtual Signer with the new key, and replace the signer in each of its vaults.

Disaster recovery (.dr) files

Once configured, the Virtual Signer writes .dr files automatically. You don't schedule or trigger anything.

The Virtual Signer writes .dr files whenever it takes part in:

  • A key generation, when it joins a new vault.
  • A reshare, whenever vault membership or weights change.

Each of those operations produces two files, one for each signature scheme, under the Broker's storage volume:

{StorageBasePath}/private-dr/{vaultId}/{signerId}/{requestId}.{algo}.{curve}.dr

For example:

/var/vsigner/private-dr/<VAULT_ID>/<SIGNER_ID>/<REQUEST_ID>.ecdsa.secp256k1.dr
/var/vsigner/private-dr/<VAULT_ID>/<SIGNER_ID>/<REQUEST_ID>.eddsa.ed25519.dr

IOSIGN_SIGNER_BROKER_STORAGE_BASE_PATH sets StorageBasePath, which defaults to /var/vsigner. The UUID at the start of the file name is the request ID of the operation, not the vault ID.

A vault accumulates many .dr files

The Virtual Signer never deletes old .dr files. Each reshare adds a new pair rather than replacing the previous one, so a vault accumulates 2 × (1 key generation + N reshares) files for each Virtual Signer in it.

This is deliberate: the recovery tool uses the full history to work out which shares are current. Because a recovery may need several of these files, signerctl collects them into a single recovery bundle for the disaster recovery tool.

Each .dr file is protected by its own ML-KEM-768 encryption, independently of any encryption at rest on the storage volume. IOSIGN_SIGNER_CORE_ENCRYPTION_KEY and Azure Secure Key Release (SKR) protect other Virtual Signer state. They don't encrypt .dr files, and you don't need them to read .dr files during a recovery.

Create a recovery bundle with signerctl

signerctl is the Virtual Signer operator command-line tool. It's built into the Broker image at /usr/local/bin/signerctl, and runs as a one-off command inside the Broker container, using the Broker's own configuration.

Configure the backup volume

signerctl writes bundles to a separate volume, which you configure with:

ConfigurationDescription
IOSIGN_SIGNER_BROKER_BACKUP_BASE_PATHDirectory that receives recovery bundles. The Broker doesn't read it at runtime. Required only for signerctl share backup.

If it's unset, the command stops with backup volume not configured: set IOSIGN_SIGNER_BROKER_BACKUP_BASE_PATH.

Export a bundle

docker compose exec vs-broker signerctl share backup

This collects every .dr file belonging to this signer into a ZIP with an integrity manifest, and checks the ZIP before reporting success:

share backup — signer=aabbccdd…0001
2 vaults: 2 ok
bundle: /var/vsigner-backups/backup-aabbccdd-0000-0000-0000-000000000001-20260709T103000Z.zip (1.2 KiB, 2 files, verified)

result: OK

The bundle is named backup-<signerId>-<timestamp>.zip. It contains a manifest.json at its root, alongside the .dr files:

backup-<signerId>-<timestamp>.zip
├── manifest.json
└── dr/
    └── {vaultId}/
        └── {signerId}/
            └── {requestId}.{algo}.{curve}.dr

The manifest lists each file and flags any problems found with it. signerctl doesn't decrypt anything while bundling: it never has the private key, and doesn't need it.

Exit codeMeaning
0Clean: no findings.
1Advisory findings: integrity problems recorded in the manifest. The bundle is still written.
2The command couldn't run. No bundle is written.

Exit code 1 is a signal to investigate, not to discard the bundle.

Related signerctl commands

CommandPurpose
signerctl signer showShow the signer identity held on this volume, and confirm it matches the signer registered with io.finnet.
signerctl share checkCompare the shares on disk with the vaults io.finnet says this signer belongs to. Add -v to list every vault.
signerctl versionPrint the version.

When to export

Export a bundle:

  • After the Virtual Signer joins a new vault.
  • After every reshare it takes part in.
  • On a regular schedule, as a safety net.

As with Mobile Signer backup files, a bundle taken before the latest reshare may not hold enough current shares to recover the vault.

Recover a vault

Recover on an air-gapped computer with the disaster recovery tool, version 6.5.0 or later. Pass each Virtual Signer's private key with -keys, alongside its bundles. You can recover with Virtual Signer bundles and Mobile Signer backups in the same run. For the full procedure, see Run the recovery tool.

The tool decrypts bundles and .dr files with the private key, so it doesn't ask for a secret phrase for them.

If you extract a bundle and zip it again by hand, zip the folder's contents, not the folder itself. The tool expects manifest.json at the root of the ZIP.

Why ML-KEM-768

The Virtual Signer encrypts .dr files with ML-KEM-768, the key encapsulation mechanism standardised by NIST as FIPS 203. It's designed to resist attack by both classical and quantum computers.

This matters for disaster recovery material because .dr files are long-lived: they sit in backups, archives, and offline media for as long as a vault exists. An attacker could copy them today and try to decrypt them once quantum hardware matures. ML-KEM-768 closes off that attack.

What to back up

ItemWhyWhere it lives
ML-KEM-768 private keyWithout it, you can't decrypt any .dr file. The Virtual Signer never stores it.Offline, with the Product Owner.
Recovery bundles from signerctl share backupA portable, integrity-checked snapshot of the signer's .dr files.IOSIGN_SIGNER_BROKER_BACKUP_BASE_PATH
The storage volumeHolds the live shares and the sealed configuration. You need it to keep the existing signer running, as opposed to recovering the vault.IOSIGN_SIGNER_BROKER_STORAGE_BASE_PATH
Encryption-at-rest keyIf you configure IOSIGN_SIGNER_CORE_ENCRYPTION_KEY or Azure SKR, you can't read volume backups without it. It doesn't affect .dr files.Your secret store.

A bundle isn't a complete signer backup. It contains only .dr files, and you can't restore a running Virtual Signer from one: it's an input to offline recovery. To restore service after losing a host, see Disaster recovery and backup.

Run drills

The failures described on this page look identical to a healthy deployment until the day you attempt a recovery: a valid but wrong public key, a private key nobody can find, or a bundle taken before the latest reshare.

Run regular air-gapped disaster recovery drills on a test vault. Generate a key pair, deploy, export a bundle, and recover it end to end. Confirm that the people who would need the private key during an incident can retrieve it from wherever your organisation stores it.


Did this page help you?