KMS Key Management

CyborgDB can persist a per-index KMS envelope — a small record describing how an index’s KEK is wrapped by an external Key Management Service. AES-256-GCM wraps the 32-byte KEK. These module-level functions read and write that envelope; the envelope itself is represented by the KMSBlob type and stored as a FlatBuffer next to the index keystore.

KMS is an advanced / optional feature primarily for the service layer. Embedded SDK users who supply their own KEK can ignore it entirely, or use provider="none" (the SDK supplies the plaintext KEK per request and nothing key-derived is stored).

Envelope model. Each index is encrypted with AES-256-GCM under a 32-byte KEK. The KMS envelope records how that KEK is wrapped by an external KMS so a service layer can unwrap it at request time. Supported providers:

• "aws" — the KEK is wrapped with AES-256-GCM under a value stored in AWS Secrets Manager.
• "aws-kms" — the KEK is wrapped via kms.Encrypt using an AWS KMS key.
• "none" — no external wrapping; the caller supplies the plaintext KEK per request and nothing is stored.

Customer-managed keys (CMK) are supported via "aws-kms", not yet for the other providers.

By default the plaintext KEK lives in caller process memory; the wrapped KEK lives next to the index keystore (StorageConfig).

All functions take a config_location (StorageConfig) identifying where the index keystore lives, plus the index name.

---

create_index_kms

Creates a KMS envelope for an index. Strict insert — fails if an envelope already exists for index_name.

def create_index_kms(config_location: StorageConfig,
                     index_name: str,
                     blob: KMSBlob)

Parameters

Parameter	Type	Description
config_location	StorageConfig	Backing store where the index keystore lives.
index_name	str	Name of the index the envelope belongs to.
blob	KMSBlob	The KMS envelope to store.

Example Usage

import cyborgdb_core as cyborgdb

config = cyborgdb.StorageConfig.disk("/tmp/cyborgdb")

blob = cyborgdb.KMSBlob(
    kms_name="prod-kms",
    provider="aws-kms",
    key_id="arn:aws:kms:us-east-1:123456789012:key/abcd-...",
    region="us-east-1",
    wrapped_kek=b"...",  # KEK wrapped by the external KMS
    version=1,
)

cyborgdb.create_index_kms(config, "my_index", blob)

---

push_index_kms

Stores a KMS envelope for an index. Idempotent upsert — creates the envelope if missing, otherwise overwrites it.

def push_index_kms(config_location: StorageConfig,
                   index_name: str,
                   blob: KMSBlob)

Parameters

Parameter	Type	Description
config_location	StorageConfig	Backing store where the index keystore lives.
index_name	str	Name of the index the envelope belongs to.
blob	KMSBlob	The KMS envelope to store (replaces any existing one).

Example Usage

# Rotate the wrapped KEK without caring whether an envelope already exists
blob.wrapped_kek = b"...new wrapped kek..."
blob.version = 2
cyborgdb.push_index_kms(config, "my_index", blob)

---

get_index_kms

Retrieves the KMS envelope for an index.

def get_index_kms(config_location: StorageConfig,
                 index_name: str) -> KMSBlob

Parameters

Parameter	Type	Description
config_location	StorageConfig	Backing store where the index keystore lives.
index_name	str	Name of the index the envelope belongs to.

Returns

KMSBlob: The stored KMS envelope for the index.

Example Usage

blob = cyborgdb.get_index_kms(config, "my_index")
print(blob.provider, blob.key_id, blob.version)

---

delete_index_kms

Deletes the KMS envelope for an index. Idempotent — deleting a non-existent envelope is a no-op.

def delete_index_kms(config_location: StorageConfig,
                    index_name: str)

Parameters

Parameter	Type	Description
config_location	StorageConfig	Backing store where the index keystore lives.
index_name	str	Name of the index the envelope belongs to.

Example Usage

cyborgdb.delete_index_kms(config, "my_index")

---

Rotation

To rotate the wrapped KEK, re-wrap it with your external KMS and store the new envelope with push_index_kms (an idempotent upsert), bumping version:

blob = cyborgdb.get_index_kms(config, "my_index")
blob.wrapped_kek = b"...newly wrapped kek..."
blob.version += 1
cyborgdb.push_index_kms(config, "my_index", blob)

For end-to-end key-rotation guidance, see the CyborgDB documentation.