Field Level Encryption from the Java SDK

Field Level Encryption is available in Couchbase Data Platform 5.5, from Java SDK version 2.6.0


The Couchbase Java SDK uses the java-couchbase-encryption library to provide support for encryption and decryption of JSON fields.

This separation of the encryption library ensures that the SDK does not have a dependency upon an encryption library in general use — but it does mean you have to explicitly include this external dependency in your project configuration. See the example project.

The Couchbase Java Field Level Encryption (FLE) uses entity annotations/JsonObject methods to specify which field(s) to apply encryption and which algorithm to use. Here’s an example POJO entity definition:

public static class Person {

    public String id;

    @EncryptedField(provider = "AES")
    public String password;

    //The rest will be transported and stored unencrypted
    public String firstName;
    public String lastName;
    public String userName;
    public int age;


Create a configuration to connect to your Couchbase cluster and configure the crypto manager in the Couchbase environment with the encryption crypto algorithm and key store providers.

The alias used for registering the provider should match the provider name string in the annotation/parameter.
JceksKeyStoreProvider kp = new JceksKeyStoreProvider("secret");
kp.storeKey("SecretKey", "mysecretkey".getBytes());
kp.storeKey("HMACsecret", "myauthsecret".getBytes());
AES256CryptoProvider aes256CryptoProvider = new AES256CryptoProvider(kp);
CryptoManager cryptoManager = new CryptoManager();
cryptoManager.registerProvider("AES", aes256CryptoProvider);
CouchbaseEnvironment environment = DefaultCouchbaseEnvironment.builder().cryptoManager(cryptoManager).build();

To apply encryption to a repository entity, use the EncryptedField annotation with provider name as registered on the crypto manager.

@EncryptedField(provider = "AES")
public String password;

Encryption can also be applied to JsonObjects.

JsonObject.create().putAndEncrypt("foo", "bar", "AES");


Encrypted fields in entities are decrypted based on the annotations. To decrypt use fields in JsonObject, use getAndDecrypt methods.

JsonDocument stored = bucket.get("mydoc");
stored.content().getAndDecrypt("foo", "AES")


There is a complete example in our devguide examples collection.