Setting up CMEK encryption with an EKM

                   ┌─────tpuf bucket────────────┐                                      
                   │  ┌────────────────────┐    │░                                     
                   │  │    namespace a     │    │░           ┌───your cloud───────────┐
──────write────────┼─▶│  (AES-256, Cloud   │    │░           │ ┌──EKM-A─────────────┐ │
                   │  │    managed key)    │    │░           │ │ ╔══════╗  ┌──────┐ │ │
                   │  └────────────────────┘    │░    ┌──────┼─┼▶║key-1 ║  │key-2 │ │ │
      write        │  ┌────────────────────┐    │░    │      │ │ ╚══════╝  └──────┘ │ │
──/EKM-A/key-1─────┼─▶│    namespace b     │    │░    │      │ └────────────────────┘ │
                   │  │(AES-256, Your Key) │◀───┼─────┘      └────────────────────────┘
                   │  │                    │    │░                                     
                   │  └────────────────────┘    │░           ┌───your customer's cloud┐
                   │  ┌────────────────────┐    │░           │ ┌─EKM-B──────────────┐ │
      write        │  │    namespace C     │    │░           │ │ ╔══════╗  ┌──────┐ │ │
──/EKM-B/key-3─────┼─▶│   (AES-256, Your   │◀───┼────────────┼─┼▶║key-3 ║  │key-4 │ │ │
                   │  │  Customer's Key)   │    │░           │ │ ╚══════╝  └──────┘ │ │
                   │  └────────────────────┘    │░           │ └────────────────────┘ │
                   └────────────────────────────┘░           └────────────────────────┘
                    ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░

By default, all data at rest is encrypted using AES-256 using the cloud provider's managed keys.

turbopuffer also supports customer managed encryption keys (CMEK) for scale and enterprise customers. When using CMEK, writes provide a key name (GCP resource ID or AWS ARN) identifying an encryption key in the customer's key management system (customer KMS) also known as External Key Manager (EKM). All namespace objects will then be encrypted with this customer provided key, which can be revoked at any time.

Enabling CMEK

Ensure you are on the scale or enterprise plan.
Open your cloud Provider's Console and create a KMS/EKM in the same region as the turbopuffer region(s) you're using.
Ask turbopuffer support to get the turbopuffer Service Account email (GCP) or account ARN (AWS).
Grant turbopuffer access to the key:

On GCP, edit the Key Ring and grant the Permission Cloud KMS CryptoKey Encrypter/Decrypter to the turbopuffer service account email.
On AWS, edit the Key Policy to add the following statement:

  {
    "Sid": "KeyUsage",
    "Effect": "Allow",
    "Principal": {
      "AWS": "<provided by turbopuffer>"
    },
    "Action": [
      "kms:ReEncrypt*",
      "kms:GenerateDataKey*",
      "kms:Encrypt",
      "kms:DescribeKey",
      "kms:Decrypt"
    ],
    "Resource": "*"
  }

Use the key name to write to your turbopuffer namespace.

When do I provide the encryption key?

The encryption key only needs to be provided on writes. All future writes will use the previously sent encryption key, which cannot be changed after the first upsert. Queries do not need to provide the encryption key; the underlying object store will transparently decrypt objects so long as turbopuffer maintains permission to use your keys.

Does CMEK impact latency or availability?

No, CMEK does not impact either availability or performance of turbopuffer.

What does it cost?

On the turbopuffer side, there is no additional cost to using CMEK on top of your plan.

The cloud will charge you based on encryption operations and the number of keys.

Does turbopuffer support key rotation?

When you rotate your cloud KMS key, turbopuffer will automatically use the latest active key version for new writes. However, turbopuffer does not automatically re-encrypt existing data. This means:

Data written before rotation remains encrypted with the previous key version
New data will be encrypted with the latest key version
You must keep all previously used key versions active to maintain access to older data
Revoking previous key versions will make that namespace permanently inaccessible

If you need to migrate all data to a new key version, use the export API to re-upsert your data into a new namespace with the desired encryption configuration. Should you find this limiting, contact us, we should be able to improve ease of key rotation.