How To Rename a Transit Key

Introduction

Vault currently does not have a direct endpoint to update the name value for an existing transit key.

This document details the how to rename an existing transit key through the backup and restore procedure. 

Expected Outcome

To update the name parameter of an existing key for the transit secrets engine while retaining same the key's value.

Prerequisites

• A running Vault server.
• Enabled transit secrets engine. 

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, ensure you have adequate backups and fully validate before attempting in production.

Procedure

Create Test Key and Data

• Create test key

  vault write -f transit/keys/test-key

• 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"-

Enable Key Exporting

• Allow exporting of key. NOTE: Once set, this cannot be disabled
  

  vault write transit/keys/test-key/config exportable=true allow_plaintext_backup=true

Begin Restore/Rename Process

• 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 and Verify new 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"

Additional Information

• Vault Documentation: Transit Secrets Engine (API)
• Vault Documentation: Vault data backup standard procedure
• Vault Tutorial: Transit secrets re-wrapping
• Vault Tutorial: Encryption as a service: transit secrets engine