How-to migrate existing transit seal key between clusters – HashiCorp Help Center

Introduction

When managing multiple Vault clusters with Transit Auto-Unseal, you may need to migrate an existing Transit key to a new Vault cluster. While the recommended approach is to temporarily switch to Shamir sealing and then reconfigure Transit Auto-Unseal with the new cluster, you can directly migrate the key material to a new cluster if necessary. This document outlines a secure and accurate process to achieve this while preserving key versioning and minimizing risks.

Procedure

1. Enable Plaintext Backup on the Existing Key

Before migrating the key, you need to allow plaintext backup temporarily on the source Transit key. This operation must be performed with caution and reverted after the backup.

vault write -f transit/keys/autounseal/config allow_plaintext_backup=true

2. Backup the Key Material

Export the key material using a secure method, ensuring the key versioning information is preserved.

curl --header "X-Vault-Token:<vault token>" \
--request GET \
https://<source vault addr>:8200/v1/transit/backup/<current key name> \
-H "Accept: application/json" > payload.json

Replace <vault token> with a token that has the transit/backup capability for the key.
Replace <source vault addr> and <current key name> appropriately.
Store payload.json securely (e.g., in a temporary encrypted storage location).

Important: Do not leave the key material in plaintext or unprotected. Limit access to this file strictly.

3. Restore the Key on the Target Cluster

Import the backed-up key material into the target Transit cluster, preserving versioning. Ensure that the key name does not already exist in the target cluster.

curl --header "X-Vault-Token:<vault token>" \
--request POST \
--data @payload.json \
https://<target vault addr>:8200/v1/transit/restore/<new key name>

Replace <target vault addr> and <new key name> appropriately.
Use a token with minimal permissions required for the restore operation.

Versioning Preservation: The restore API automatically includes versioning details from the backup file, ensuring key continuity.

4. Revert Plaintext Backup Permission

On the source Vault cluster, immediately disable plaintext backups after exporting the key.

vault write -f transit/keys/autounseal/config allow_plaintext_backup=false

This step secures the source key from further plaintext backup attempts.

5. Update Vault Configuration

Modify the Vault configuration file (vault.hcl) to use the new Transit key in the target cluster.

hcl:

seal "transit" {
token = "<new token>"
address = "https://<target vault addr>:8200"
disable_renewal = false
key_name = "<new key name>"
mount_path = "transit/"
tls_skip_verify = false
}

Security Considerations:

Use a minimally privileged token with access only to the restore API and the specified key.
Ensure TLS is properly configured (tls_skip_verify=false) to avoid potential man-in-the-middle attacks.

6. Restart the Vault Node

Restart the Vault node to apply the updated configuration.

systemctl restart vault

After restarting, ensure the Vault node unseals correctly using the new Transit key.

7. Verify Key Migration and Operations

Test key decryption operations to confirm that the migrated key works as expected.
Check for any key version mismatches between the source and target clusters.
Audit logs to ensure no unauthorized access occurred during the migration process.

Additional Recommendations

Backup Payload Encryption: Consider encrypting payload.json using a secure tool (e.g., gpg) during transit and storage.
Audit Logging: Enable detailed audit logging during the migration process for both source and target Vault clusters.
Test Environment: Perform the migration in a test environment before applying it to production.
Key Retirement: After a successful migration, deprecate and retire the old Transit key if it is no longer required.

Summary

This procedure ensures a secure migration of a Transit key while preserving key versioning and minimizing operational risks. By following these steps and adhering to Vault best practices, you can safely migrate your Transit Auto-Unseal key between clusters.

Additional Information