Skip to content

Migration to Envelope Encryption for Existing Customers

Purpose

This document describes how existing customers transition to the new envelope encryption setup (KEK/DEK). The goal is a seamless transition: existing encrypted data stays readable, no data has to be re-encrypted, and the legacy crypto key can be retired once the migration is complete.

Background

Until now, each customer's data was encrypted with a single crypto key that was retrieved and used directly. In the new setup, encryption follows the envelope encryption model:

  • KEK (Key Encryption Key): an RSA key stored in Azure Key Vault. It is only used to wrap and unwrap DEKs.
  • DEK (Data Encryption Key): an AES-256 key per entity that encrypts the actual data. The DEK is stored in the Key Vault as a secret named wrapped-dek-<entity>, in wrapped (encrypted) form.

For a more detailed explenation of envelope encryption, check Data Privacy.

Approach for existing customers

For existing customers, the current secret that is used for encryption is reused as the DEK. Its value does not change. It is wrapped with the KEK and stored in the Key Vault as wrapped-dek-<entity>.

Because the key value stays the same:

  • The decrypt logic still support the old way of decrypting with a crypto key. Changes need to be made to decrypt according to the KEK and DEK structure.

Decryption keeps working exactly as it did until it is switched over to the new way of retrieving the DEK (Step 1 below).

Migration steps

Step 1: Update custom notebook encryption and decryption

For encryption with deks, an encryption_v2 module has been made. Decryption is changed to retrieve the wrapped DEK from the Key Vault instead of using the legacy crypto key. Check Custom Notebook on how to implement this into existing custom notebooks. Make sure all the privacy entities have run atleast once in the new format, so they all have a valid DEK.

Step 2: Remove the legacy crypto key

Once encrytion in custom notebooks and decryption has been updated (Step 1), the legacy crypto key (secret in the key vault) can be removed. The migration to the KEK/DEK setup itself runs automatically; the crypto key only needs to be removed to make the DEKs unique per entity: as long as the crypto key is supplied, it is used as the DEK, so the DEK is the legacy key rather than a key generated for that entity. Once decryption retrieves the wrapped DEK from the Key Vault and the crypto key is removed, each new entity's DEK is a genuine, entity-specific DEK. All the existing DEK remain the same and will be unchanged.

Benefits

  • A real DEK, unique per entity: after the crypto key is removed, the key that encrypts an entity's data is an actual unique DEK for the newly DEKS (thus new privacy entities), protected by a KEK, instead of a standalone crypto key. Existing DEKS will still use the same DEK.
  • Central key protection: the DEK is only stored in wrapped form, so it is useless without access to the KEK in the Key Vault.
  • No data impact: since the key value is unchanged, no re-encryption of existing data is required.

Summary

Aspect Before After
Key used for data Crypto key DEK (same value for existing customers)
Key storage Retrieved as crypto key Wrapped by KEK, stored as wrapped-dek-<entity>
Legacy crypto key Required Removed, so DEKs become unique per entity