Transparent Data Encryption (TDE) encrypts the files PostgreSQL writes to disk while queries, backups and restores carry on unchanged — a stolen data directory yields nothing readable. Everything then hinges on where the encryption key lives: a key in a configuration file is a key in the attacker's hands, and a key only in an administrator's memory blocks unattended start-up. CYBERTEC PostgreSQL Enterprise Edition delegates the problem to pgee_key_manager, a helper that generates the TDE data encryption key, stores it encrypted on disk, and releases the plaintext to PostgreSQL only when the server asks — backed by whatever key management you already operate.

The hook into PostgreSQL

TDE needs the key at start-up, during initdb, and for maintenance such as pg_upgrade. PostgreSQL obtains it through encryption_key_command, a program whose standard output is the key; pgee_key_manager fills that role, and whatever is needed to recover the key lives either in tdekey.json or in the configured key service.

Three properties make this dependable in production:

  • Only PostgreSQL and its utilities receive the key on stdout; an interactive shell invocation gets nothing.
  • An unreachable, slow or misbehaving key service produces a non-zero exit and empty stdout — the tool fails closed, and the server refuses to start rather than start with the wrong key.
  • tdekey.json is written atomically with permissions 0600 and contains only ciphertext and version numbers. URLs, paths and credentials are supplied on each call, so the file remains portable.

Two keys, not one

The design separates the AES data encryption key (DEK, 128, 192 or 256 bits) that encrypts database files from the wrapping secret or key that protects the DEK. The DEK is never stored in plaintext: tdekey.json carries it encrypted under the wrapping secret, which lives in a key service. Relocating that protection leaves the database files untouched.

Protection comes in two flavours. Password stores hold a random password in the service; the DEK is encrypted with it and tdekey.json records which password version was used — this covers HashiCorp Vault, Azure Key Vault, CyberArk Conjur and the built-in bootstrap. Wrapping stores hand the DEK to the service and receive it back encrypted under a key that never leaves the service, so no password exists at all — AWS KMS, Google Cloud KMS and KMIP behave this way.

The backends

local: for bootstrap only

Without a backend flag the DEK is encrypted with a password compiled into the binary and stored as method: local, letting initdb create a key before any service exists. It is weak, and real data should not live behind it.

HashiCorp Vault and OpenBao

-vault keeps the wrapping password in a Vault KV v2 secret (default secret/data/pgee, key tdekey_password) and records the secret version. It requires create, read and update on that path, and no metadata access. OpenBao exposes the same API, so the same flags apply.

Version retention demands care: tdekey.json points at one version, and if other writers push it out of the mount's history the DEK can no longer be decrypted. Only the tool should write to the secret.

AWS KMS

With -aws-key-id, the DEK is wrapped directly by a symmetric KMS key and the ciphertext goes into tdekey.json. The IAM principal needs kms:Encrypt, kms:Decrypt and kms:DescribeKey; the third lets the tool detect AWS's own key-material rotation, after which the DEK is re-wrapped on the next start.

Azure Key Vault

-azure stores the wrapping password as a Key Vault secret (default tdekey-password) with its version recorded. Authentication goes through DefaultAzureCredential, covering managed identity, workload identity, environment variables and az login. The identity needs readSecret and writeSecret, plus setSecret while the secret does not yet exist. Key Vault keys and Managed HSM key wrapping are not supported — secrets only.

Google Cloud KMS

-google-kms wraps directly like AWS, using a symmetric CryptoKey identified by its full resource path (projects/P/locations/L/keyRings/R/cryptoKeys/K), with CRC32C verification on requests and responses. Required permissions are useToEncrypt, useToDecrypt and cloudkms.cryptoKeys.get. The last is commonly overlooked: the predefined Cloud KMS CryptoKey Encrypter/Decrypter role omits it and decryption fails without it. A new primary version is picked up and the DEK re-wrapped.

KMIP

KMIP, the OASIS Key Management Interoperability Protocol, is the broadest option: any compliant server can hold the wrapping key. -kmip authenticates with mutual TLS (the client certificate is the identity), has the server create an AES-256 wrapping key or reuses one named via -kmip-key-id, activates it, and leaves AES-GCM to the server. Ciphertext is formatted as base64( IV || ciphertext || tag ), and the wrapping key's managed object id is recorded in tdekey.json.

Not every product marketed as a KMIP server qualifies: many manage lifecycles only, whereas this backend requires server-side Encrypt and Decrypt with AES-GCM. Documented examples that work include Cosmian KMS (used in the test suite), Thales CipherTrust Manager and Fortanix Data Security Manager, with more in the project guide. HashiCorp's Vault Enterprise KMIP secrets engine and Infisical KMS implement lifecycle operations only and cannot be used. Since KMIP keys are unversioned, rotation is always explicit: -rotate creates a new wrapping key, re-wraps the DEK and keeps the old key for older backups.

CyberArk Conjur

-conjur keeps the wrapping password in a Conjur variable (default pgee/tdekey_password) and records its version. The host identity needs read to see existing versions, execute to read the value and update to write a new one. Conjur OSS, Conjur Enterprise and Secrets Manager all work, over plain HTTPS and without the Conjur SDK.

Conjur retains only the most recent 20 versions of a variable. Write more without an intervening re-wrap and the recorded version is purged, making the DEK unrecoverable. Restrict update to pgee_key_manager and keep an offline copy of the DEK.

At a glance

Key store Flag What protects the data key
Built-in (bootstrap) (none) Fixed password in the binary; weak by design
HashiCorp Vault / OpenBao -vault Random password in a KV v2 secret
AWS KMS -aws-key-id DEK encrypted by a KMS key
Azure Key Vault -azure Random password in a Key Vault secret
Google Cloud KMS -google-kms DEK encrypted by a Cloud KMS key
KMIP server -kmip DEK encrypted (AES-GCM) by a key on the server
CyberArk Conjur -conjur Random password in a Conjur variable

Migrating and rotating

Since the DEK is independent of the wrapping secret, a cluster moves between key services with a single command run in $PGDATA: the tool decrypts using the old backend (reachable once more), writes the new secret into the new service and rewrites tdekey.json. Point encryption_key_command at the new flag and restart; the database files are never touched.

Rotation follows from the same separation. -rotate replaces the wrapping secret or key and re-wraps the DEK without re-encrypting the database, so it completes in moments. Where a service schedules its own key rotation, as AWS and Google do, no action is needed — the next start notices and re-wraps. For password stores, the new secret is always written before tdekey.json is replaced, so a failed write leaves the previous file functional.

Selection and operational rules

The sensible default is whatever your organisation already runs and audits: a provider's KMS on a cloud VM, HashiCorp Vault or OpenBao on premises, or an existing HSM or key manager appliance that speaks KMIP. Vault's Transit engine, PKCS#11 HSMs and Azure Key Vault keys are frequently requested but not yet supported.

Two things decide whether recovery works. A backup is only a backup if you can restore both the data directory with its tdekey.json and the key-service state that file references — the secret version, the KMS key or the KMIP wrapping key; losing either prevents the cluster from starting. And because the tool prints the key only to PostgreSQL, it will not surrender an existing key for safekeeping. To hold an offline copy, generate and import your own:

openssl rand -hex 32 | tee /safe/offline-copy | pgee_key_manager -import

With that copy, a lost tdekey.json can be rebuilt by moving the old file aside and importing again.