Using a key store

Suggest edits

You can use the key store in an external key management system to manage the data encryption key. The tested and supported key stores are:

  • Amazon AWS Key Management Service (KMS)
  • Microsoft Azure Key Vault
  • Google Cloud - Cloud Key Management Service
  • HashiCorp Vault (KMIP Secrets Engine and Transit Secrets Engine)
  • Thales CipherTrust Manager
  • Fortanix Data Security Manager

To use one of the available key stores, see the configuration examples.

AWS Key Management Service example

Create a key with AWS Key Management Service:

aws kms create-key
aws kms create-alias --alias-name alias/pg-tde-master-1 --target-key-id "..."

Use the aws kms command with the alias/pg-tde-master-1 key to wrap and unwrap the data encryption key:

PGDATAKEYWRAPCMD='aws kms encrypt --key-id alias/pg-tde-master-1 --plaintext fileb:///dev/stdin --output text --query CiphertextBlob | base64 -d > "%p"'
PGDATAKEYUNWRAPCMD='aws kms decrypt --key-id alias/pg-tde-master-1 --ciphertext-blob fileb://"%p" --output text --query Plaintext | base64 -d'
Note

Shell commands with pipes, as in this example, are problematic because the exit status of the pipe is that of the last command. A failure of the first, more interesting command isn't reported properly. Postgres handles this somewhat by recognizing whether the wrap or unwrap command wrote nothing. However, it's better to make this more robust. For example, use the pipefail option available in some shells or the mispipe command available on some operating systems. Put more complicated commands into an external shell script or other program instead of defining them inline.

Azure Key Vault example

Create a key with Azure Key Vault:

az keyvault key create --vault-name pg-tde --name pg-tde-master-1

Use the az keyvault key command with the pg-tde-master-1 key to wrap and unwrap the data encryption key:

PGDATAKEYWRAPCMD='az keyvault key encrypt --name pg-tde-master-1 --vault-name pg-tde --algorithm A256GCM --value @- --data-type plaintext --only-show-errors --output json | jq -r .result > "%p"'
PGDATAKEYUNWRAPCMD='az keyvault key decrypt --name pg-tde-master-1 --vault-name pg-tde --algorithm A256GCM --value @"%p" --data-type plaintext --only-show-errors --output json | jq -r .result'
Note

Shell commands with pipes, as in this example, are problematic because the exit status of the pipe is that of the last command. A failure of the first, more interesting command isn't reported properly. Postgres handles this somewhat by recognizing whether the wrap or unwrap command wrote nothing. However, it's better to make this more robust. For example, use the pipefail option available in some shells or the mispipe command available on some operating systems. Put more complicated commands into an external shell script or other program instead of defining them inline.

Google Cloud KMS example

Create a key with Google Cloud KMS:

gcloud kms keys create pg-tde-master-1 --location=global --keyring=pg-tde --purpose=encryption

Use the gcloud kms command with the pg-tde-master-1 key to wrap and unwrap the data encryption key:

PGDATAKEYWRAPCMD='gcloud kms encrypt --plaintext-file=- --ciphertext-file=%p --location=global --keyring=pg-tde --key=pg-tde-master-1'
PGDATAKEYUNWRAPCMD='gcloud kms decrypt --plaintext-file=- --ciphertext-file=%p --location=global --keyring=pg-tde --key=pg-tde-master-1'

HashiCorp Vault Transit Secrets Engine example

Enable transit with HashiCorp Vault Transit Secrets Engine:

vault secrets enable transit

Create a key and give it a name:

vault write -f transit/keys/pg-tde-master-1

Use the vault write command with the pg-tde-master-1 key to wrap and unwrap the data encryption key:

PGDATAKEYWRAPCMD='base64 | vault write -field=ciphertext transit/encrypt/pg-tde-master-1 plaintext=- > %p'
PGDATAKEYUNWRAPCMD='vault write -field=plaintext transit/decrypt/pg-tde-master-1 ciphertext=- < %p | base64 -d'

Thales CipherTrust Manager example

See the Using section of the Implementing Thales CipherTrust Manager documentation for instructions how to wrap the data encryption key with a key from the Thales key store.

Fortanix Data Security Manager example

See Using Fortanix Data Security Manager with EDB Postgres for TDE for a step-by-step configuration tutorial.

← Prev

Using a passphrase

↑ Up

Securing the data encryption key

Next →

Disabling the key wrapping