Introduction
Expected Outcome
To update the name parameter of an existing key for the transit secrets engine while retaining same the key's value.
Prerequisites (if applicable)
- A running Vault server.
Use Case
- Customer's often inquire about how to rename an existing transit secrets engine key without having to create an entirely new key.
- The motivation behind this inquiry is they would like to change the name parameter for the key without altering the underlying key material.
- There is not a direct endpoint in Vault to update the name value for an existing key.
- Instead, operators will need to backup the existing key and restore the key to the secrets engine with a new name. That procedure is documented below.
PLEASE NOTE: That this is a highly sensitive operation and this code is meant only as an example. You should take care to test the process out in a non production environment and fully validate before attempting in production.
Procedure
-
Create base64 encoded text
PLAINTEXT=$(base64 <<< "I am secret text")
-
Encrypt the text with the original key
CIPHERTEXT=$(vault write -field=ciphertext transit/encrypt/test-key plaintext=$PLAINTEXT)
-
Decrypt the text with the original key
DECRYPTED_PLAIN_TEXT=$(vault write -field=plaintext transit/decrypt/test-key ciphertext=$CIPHERTEXT)
-
Confirm that the original text and decrypted text match
[[ "$PLAINTEXT" == "$DECRYPTED_PLAIN_TEXT" ]] && echo "original text and decrypted match" || echo "original text and decrypted text do NOT match"-
- Allow exporting of key. NOTE: Once set, this cannot be disabled
vault write transit/keys/test-key/config exportable=true allow_plaintext_backup=true
- Backup the original key
vault read transit/backup/test-key -format=json | jq -r '.data.backup' > backup.key
- Restore they key with the new name
vault write transit/restore/restored-test-key backup=@backup.key
- Decrypt ciphertext with the restored key
DECRYPTED_PLAIN_TEXT_FROM_RESTORED_KEY=$(vault write -field=plaintext transit/decrypt/restored-test-key ciphertext=$CIPHERTEXT)
- Confirm that the original text and the decrypted text match
[[ "$PLAINTEXT" == "$DECRYPTED_PLAIN_TEXT_FROM_RESTORED_KEY" ]] && echo "original text and decrypted match" || echo "original text and decrypted text do NOT match"