fle-java

name	fle-java
summary	Field-Level Encryption with the Couchbase Java SDK — CryptoManager setup, @Encrypted annotation, encrypting and decrypting document fields
description	Field-Level Encryption with the Couchbase Java SDK — CryptoManager setup, @Encrypted annotation, encrypting and decrypting document fields
compatibility	Java SDK 3.x. couchbase-encryption artifact 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-java"}]}

Field-Level Encryption — Java

Setup

<!-- pom.xml -->
<dependency>
    <groupId>com.couchbase.client</groupId>
    <artifactId>couchbase-encryption</artifactId>
    <version>3.0.0</version>
</dependency>

Configure CryptoManager

import com.couchbase.client.encryption.AeadAes256CbcHmacSha512Provider;
import com.couchbase.client.encryption.DefaultCryptoManager;
import com.couchbase.client.encryption.Keyring;
import com.couchbase.client.java.Cluster;
import com.couchbase.client.java.ClusterOptions;
import com.couchbase.client.java.env.ClusterEnvironment;

byte[] keyBytes = new byte[64]; // 64-byte key for AES-256
Keyring keyring = Keyring.fromMap(Map.of("my-key-id", keyBytes));
AeadAes256CbcHmacSha512Provider provider =
    AeadAes256CbcHmacSha512Provider.builder().keyring(keyring).build();

CryptoManager cryptoManager = DefaultCryptoManager.builder()
    .decrypter(provider.decrypter())
    .defaultEncrypter(provider.encrypterForKey("my-key-id"))
    .build();

ClusterEnvironment env = ClusterEnvironment.builder()
    .cryptoManager(cryptoManager)
    .build();

Cluster cluster = Cluster.connect("couchbase://localhost",
    ClusterOptions.clusterOptions("username", "Password!123").environment(env));

Encrypting Fields with @Encrypted Annotation

import com.couchbase.client.java.encryption.annotation.Encrypted;

public class UserDocument {
    public String name;

    @Encrypted
    public String ssn;

    @Encrypted
    public String creditCard;
}

// Write
UserDocument user = new UserDocument();
user.name = "Alice";
user.ssn = "123-45-6789";
user.creditCard = "4111111111111111";

collection.upsert("user::alice", user);

// Read — decryption is automatic
UserDocument result = collection.get("user::alice").contentAs(UserDocument.class);
System.out.println(result.ssn); // "123-45-6789"

Encrypting JsonObject Fields

JsonObject doc = JsonObject.create()
    .put("name", "Alice")
    .put("ssn", "123-45-6789");

collection.upsert("user::alice", doc,
    UpsertOptions.upsertOptions().encryptFields(Set.of("ssn")));

Limitations

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