fle

name	fle
summary	Field-Level Encryption (FLE) in Couchbase — client-side encryption of specific document fields before writing to the server, supported SDKs, key management
description	Field-Level Encryption (FLE) in Couchbase — client-side encryption of specific document fields before writing to the server, supported SDKs, key management
metadata	{"last_verified":"2026-05","min_server_version":"6.0","handoff":[{"condition":"user asks about FLE in Python","type":"variant","skill":"fle-python"},{"condition":"user asks about server-side encryption at rest or TLS","skill":"security"}]}

Field-Level Encryption (FLE)

FLE encrypts specific document fields on the client before the data reaches Couchbase Server. The server stores ciphertext — it never sees plaintext for encrypted fields. Decryption happens on the client when reading.

When to Use FLE

• Regulatory compliance (PCI-DSS, HIPAA, GDPR) requiring field-level protection
• Encrypting PII (SSNs, credit card numbers, health data) while keeping other fields queryable
• Multi-tenant environments where different tenants need different encryption keys

FLE is not a substitute for TLS (in-transit encryption) or server-side encryption at rest — use all three for defence in depth.

How It Works

1. Configure a CryptoManager with a KeyProvider that holds your encryption keys.
2. Register the CryptoManager with the cluster at connection time.
3. Annotate fields (or specify field names at write time) to encrypt.
4. On upsert, the SDK encrypts annotated fields and stores them as {"alg":"...", "ciphertext":"..."} objects.
5. On get, the SDK decrypts annotated fields transparently.

Supported SDKs

SDK	Supported
Python	✅
Java	✅
Go	✅
.NET	✅
Node.js	✅
PHP	✅
Rust 1.0	❌
Scala	❌
Ruby 3.x	❌

For unsupported SDKs, use server-side encryption at rest (available in Couchbase Server 8.x) or encrypt fields in application code before passing to the SDK.

Key Management

Keys are managed by your application via a KeyProvider. In production:

• Store keys in a KMS (AWS KMS, HashiCorp Vault, Azure Key Vault)
• Rotate keys regularly — FLE supports key rotation without re-encrypting all data at once
• Never log or expose key material

Limitations

• Encrypted fields cannot be indexed or queried with SQL++ — the server only sees ciphertext
• FLE adds ~30% overhead to encrypted field size
• Schema changes to encrypted fields require re-encryption of existing documents

Language-Specific Skills

Language	Skill
Python	fle-python
Java	fle-java
Go	fle-go
.NET	fle-dotnet
Node.js	fle-nodejs
PHP	fle-php
Rust	fle-rust
Scala	fle-scala
Ruby	fle-ruby