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 thetransit/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.
- 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.