docs: clarify how to set backup encryption key#3675
Open
netrome wants to merge 1 commit into
Open
Conversation
Pull request overviewDocumentation-only PR clarifying how to configure the backup encryption key during node migration, especially the divergence between TDX/CVM nodes (set in Changes:
Reviewed changesPer-file summary
FindingsVerified the substantive claims against the codebase:
No blocking issues — the documentation is accurate and resolves a real operator footgun. ✅ Approved |
Contributor
There was a problem hiding this comment.
Pull request overview
Updates operator documentation to reduce migration failures by clarifying how the backup encryption key must be configured—especially for TDX/CVM deployments where environment variables and filesystem access differ from non-TEE nodes.
Changes:
- Document
secrets.secret_store_key_hexandsecrets.backup_encryption_key_hexrequirements in the TDX external guide. - Update the node migration guide to distinguish TDX/CVM vs non-TEE key configuration paths and add stronger warnings about CVM unrecoverable auto-generated keys.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| docs/running-an-mpc-node-in-tdx-external-guide.md | Adds explicit guidance for required secret keys in user-config.toml, including generation commands and CVM-specific constraints. |
| docs/node-migration-guide.md | Clarifies how/where to set the migration transport encryption key for TDX/CVM vs non-TEE nodes; adds CVM-specific warnings and redeploy note. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ### Retrieve a key from an existing node. | ||
|
|
||
| **Note:** If your node has been running without the `MPC_BACKUP_ENCRYPTION_KEY_HEX` environment variable set, the node automatically generates an encryption key and stores it in a file called `backup_encryption_key.hex` in your `$MPC_HOME_DIR` directory. You can retrieve it with: | ||
| **Note:** If your node has been running without an encryption key configured, the node automatically generates one and stores it in a file called `backup_encryption_key.hex` in your home directory. On a **non-TEE** node you can retrieve it with: |
Comment on lines
+139
to
+143
| **How you configure the key on a node depends on the deployment type** (see [Step 5](#step-5-prepare-the-new-node) for the exact placement): | ||
| - **TDX / CVM node:** set `backup_encryption_key_hex` under `[mpc_node_config.secrets]` in `user-config.toml`. There is **no** `MPC_BACKUP_ENCRYPTION_KEY_HEX` environment-variable pathway into a CVM — the `.env` used by `deploy-launcher.sh` is not read for this key. | ||
| - **Non-TEE node:** set the `MPC_BACKUP_ENCRYPTION_KEY_HEX` environment variable. | ||
|
|
||
| **Important:** The backup encryption key must be the same between the backup-cli and the node it is currently communicating with (e.g., the old node when running `get-keyshares`, and the new node when running `put-keyshares`). The node requires exactly 64 hex characters (32 bytes) with no surrounding whitespace, and **fails to start** if the configured value is malformed. |
gilcu3
approved these changes
Jun 25, 2026
|
|
||
| Copy this key and set it as the `BACKUP_ENCRYPTION_KEY` environment variable for the backup-cli when running `get-keyshares`. | ||
|
|
||
| > **⚠️ TDX / CVM source nodes:** you **cannot** retrieve an auto-generated key this way — there is no filesystem access into the CVM. If a CVM node was deployed without `backup_encryption_key_hex` set in its `user-config.toml`, the key it generated internally is unrecoverable and the node **cannot be migrated off**. Always set `backup_encryption_key_hex` explicitly when deploying a CVM node so you know the key. (The shipped `user-config.toml` template makes this field a required, non-hex placeholder so a forgotten value fails loudly at startup rather than silently auto-generating.) |
Contributor
There was a problem hiding this comment.
oh this seems really dangerous. Shouldn't we fail instead if no key is provided?
Collaborator
Author
There was a problem hiding this comment.
Yeah that would be better, iirc this was just introduced for backwards compatibility when we introduced the field for the 3.0.0 release since we could not add new env variables at that time.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
closes #3674