fle-python

name	fle-python
summary	Field-Level Encryption with the Couchbase Python SDK — CryptoManager setup, encrypting and decrypting document fields, key rotation
description	Field-Level Encryption with the Couchbase Python SDK — CryptoManager setup, encrypting and decrypting document fields, key rotation
compatibility	Python SDK 4.x. couchbase-encryption package required.
metadata	{"last_verified":"2026-05","min_server_version":"6.0","handoff":[{"condition":"user asks about FLE concepts or supported SDKs","skill":"fle"},{"condition":"user asks about connection setup","skill":"server-connection-python"}]}

Field-Level Encryption — Python

Setup

pip install couchbase couchbase-encryption

Configure CryptoManager

from couchbase.cluster import Cluster, ClusterOptions
from couchbase.auth import PasswordAuthenticator
from cbencryption import AeadAes256CbcHmacSha512Provider, DefaultCryptoManager, Key

# Create a key provider with your encryption key
key = Key("my-key-id", b'\x00' * 64)  # 64-byte key for AES-256
provider = AeadAes256CbcHmacSha512Provider(key)

crypto_manager = DefaultCryptoManager()
crypto_manager.register_encrypter_alias("my-encrypter", provider.encrypter())
crypto_manager.register_decrypter(provider.decrypter())

cluster = Cluster(
    "couchbase://localhost",
    ClusterOptions(
        PasswordAuthenticator("username", "Password!123"),
        crypto_manager=crypto_manager
    )
)
collection = cluster.bucket("myapp").default_collection()

Encrypting Fields on Write

Specify which fields to encrypt using encrypt_fields:

from couchbase.options import UpsertOptions
from cbencryption import EncryptedField

doc = {
    "name": "Alice",
    "ssn": "123-45-6789",       # will be encrypted
    "credit_card": "4111111111111111"  # will be encrypted
}

collection.upsert(
    "user::alice",
    doc,
    UpsertOptions(
        encrypt_fields={
            "ssn": "my-encrypter",
            "credit_card": "my-encrypter"
        }
    )
)

Decrypting Fields on Read

Decryption is automatic when the CryptoManager is configured:

result = collection.get("user::alice")
doc = result.content_as[dict]
# doc["ssn"] is automatically decrypted to "123-45-6789"
print(doc["ssn"])

Key Rotation

# Register new key alongside old key
new_key = Key("my-key-id-v2", b'\x01' * 64)
new_provider = AeadAes256CbcHmacSha512Provider(new_key)
crypto_manager.register_encrypter_alias("my-encrypter", new_provider.encrypter())
crypto_manager.register_decrypter(new_provider.decrypter())
# Old decrypter stays registered so existing documents can still be read
crypto_manager.register_decrypter(provider.decrypter())

Limitations

• Encrypted fields cannot be indexed or queried with SQL++
• Adds ~30% overhead to encrypted field size
• See fle for full concept reference