PolarDB:Transparent data encryption (TDE)

Key structure

TDE uses a two-layer key hierarchy:

• Top layer — KEK: Protects the data encryption key. Retrieved externally on each startup via the polar_cluster_passphrase_command parameter (for example, from a Key Management Service (KMS) or, for testing, echo passphrase).

• Bottom layer — data encryption keys (MDEK, TDEK, WDEK): Perform the actual encryption of data pages and WAL records.

The ENCMDEK and KEK_HMAC are saved on shared storage in the global/kmgr file (KmgrFileData structure), so every node in the cluster — primary and read-only — can recover the data encryption keys at startup. This file is created during database initialization (initdb), which means standby nodes can obtain it via pg_basebackup.

When the cluster is running, key material is held in process memory:

static keydata_t keyEncKey[TDE_KEK_SIZE];
static keydata_t relEncKey[TDE_MAX_DEK_SIZE];
static keydata_t walEncKey[TDE_MAX_DEK_SIZE];
char *polar_cluster_passphrase_command = NULL;
extern int data_encryption_cipher;

Key initialization

Keys are generated once during database initialization:

1. Run polar_cluster_passphrase_command to get the 32-byte KEK and 32-byte HMACK.

2. Call the OpenSSL random number generator to produce the MDEK.

3. Derive the TDEK from the MDEK using HKDF (OpenSSL).

4. Derive the WDEK from the MDEK using HKDF (OpenSSL).

5. Encrypt the MDEK with the KEK to produce the ENCMDEK.

6. Generate the KEK_HMAC from the ENCMDEK and HMACK using the HMAC algorithm.

7. Write the ENCMDEK, KEK_HMAC, and other KmgrFileData fields to the global/kmgr file.

The KmgrFileData structure on disk:

typedef struct KmgrFileData
{
    /* version for kmgr file */
    uint32      kmgr_version_no;

    /* Are data pages encrypted? Zero if encryption is disabled */
    uint32      data_encryption_cipher;

    /*
     * Wrapped Key information for data encryption.
     */
    WrappedEncKeyWithHmac tde_rdek;
    WrappedEncKeyWithHmac tde_wdek;

    /* CRC of all above ... MUST BE LAST! */
    pg_crc32c   crc;
} KmgrFileData;

Key decryption (on restart)

When the database restarts or recovers from a crash, TDE reconstructs the data encryption keys from the stored ciphertext:

1. Read the global/kmgr file to get the ENCMDEK and KEK_HMAC.

2. Run polar_cluster_passphrase_command to get the KEK and HMACK.

3. Generate KEK_HMAC' from the ENCMDEK and HMACK using HMAC. If it matches the stored KEK_HMAC, proceed. If not, return an error.

4. Decrypt the ENCMDEK with the KEK to recover the MDEK.

5. Derive the TDEK from the MDEK using HKDF (deterministic — same MDEK always produces the same TDEK).

6. Derive the WDEK from the MDEK using HKDF (deterministic — same MDEK always produces the same WDEK).

Key rotation

Key rotation re-encrypts the MDEK under a new KEK without changing the MDEK itself, so all existing data remains readable after rotation. The process updates the global/kmgr file with the new ENCMDEK and KEK_HMAC.

1. Read the global/kmgr file to get the ENCMDEK and KEK_HMAC.

2. Run polar_cluster_passphrase_command to get the current KEK and HMACK (64 bytes total).

3. Generate KEK_HMAC' from the ENCMDEK and HMACK using HMAC. If it matches the stored KEK_HMAC, proceed. If not, return an error.

4. Decrypt the ENCMDEK with the KEK to recover the MDEK.

5. Run polar_cluster_passphrase_command again to get the new KEK (new_KEK) and new HMACK (new_HMACK).

6. Encrypt the MDEK with new_KEK to produce new_ENCMDEK.

7. Generate new_KEK_HMAC from new_ENCMDEK and new_HMACK using HMAC.

8. Write new_ENCMDEK, new_KEK_HMAC, and other KmgrFileData fields to the global/kmgr file.