Skip to content

Storing User Keys in OVH KMS

TCE can use OVH's KMS HTTP API to encrypt and decrypt envelope keys.

Requirements

The starting point of this how-to is:

  • An up and running PostgreSQL instance
  • The Cryptic Elephant is installed
  • An OVH KMS instance is reachable from the PostgreSQL host
  • A bearer token is available for the OVH KMS API
  • An okmsId exists and each database role has its own keyId

Principles

The TCE extension within Postgres connects to OVH KMS using a credentials file. The security label continues to carry only the user key identifier.

flowchart
    subgraph ovhKms [OVH KMS]
    token[BearerToken]
    okmsId[OkmsId]
    keyId[ServiceKeyId]
    end

    subgraph postgres [Postgres]
    credentials[CredentialsIni] --> token
    credentials --> okmsId
    role[Role] --> keyId
    end

Add a Credential File

On the Postgres host:

Create the OVH configuration file. By default it is expected at /var/lib/postgres/.config/ovh/credentials.ini unless tce.kms.ovh.credentials_file overrides it.

server_url="https://<ovh-region-url>.okms.ovh.net"
okms_id=<my-okms-id>

[alice]
token="<alice-bearer-token>"

[bob]
token="<bob-bearer-token>"

The plaintext data sent to OVH is base64-encoded by TCE before the /encrypt request. The plaintext data returned by /decrypt is expected to be base64 too and is decoded back into raw envelope-key bytes.

Configure the TCE Extension

Connect to the Postgres instance and configure the database to use the OVH KMS provider:

CREATE DATABASE demo;
ALTER DATABASE demo SET session_preload_libraries TO 'tce';
ALTER DATABASE demo SET tce.kms.type TO 'ovh';
ALTER DATABASE demo SET tce.kms.ovh.credentials_file TO '/var/lib/postgres/.config/ovh/credentials.ini';

If you use profile sections, set the OVH profile at the database or role level:

ALTER ROLE alice SET tce.kms.ovh.profile TO 'alice_profile';
ALTER ROLE bob SET tce.kms.ovh.profile TO 'bob_profile';

Create Roles

The security label still uses HOSTED ON KMS USING <keyId>:

\connect demo

CREATE EXTENSION tce;

CREATE ROLE alice LOGIN;
SECURITY LABEL FOR tce_user_key ON ROLE alice
  IS 'HOSTED ON KMS USING <alice-keyId>';

CREATE ROLE bob LOGIN;
SECURITY LABEL FOR tce_user_key ON ROLE bob
  IS 'HOSTED ON KMS USING <bob-keyId>';

OVH Endpoints Used by TCE

TCE calls the following OVH KMS HTTP endpoints:

  • POST /api/{okmsId}/v1/servicekey/{keyId}/encrypt
  • POST /api/{okmsId}/v1/servicekey/{keyId}/decrypt

Each request has the authentication header with the given Bearer Token.

The request bodies are expected to be, for encrypt:

{
  "plaintext": "<base64-encoded envelope key>",
  "context": "pg_tce"
}

and for decrypt

{
  "ciphertext": "<base64-encoded ciphered envelope key>",
  "context": "pg_tce"
}