Field Level Encryption from the Java SDK

    A practical guide for getting started with Field-Level Encryption, showing how to encrypt and decrypt JSON fields using the Java SDK.

    For a high-level overview of this feature, see Field Level Encryption.


    The Couchbase Java SDK works together with the Java Couchbase Encryption library to provide support for encryption and decryption of JSON fields. This library includes cryptographic algorithms and keyrings you can use out of the box, and provides a framework for implementing your own crypto components.

    The encryption code is packaged as an optional library because it is released under a different license than the Couchbase Java SDK. To use the encryption library, you have to explicitly include this dependency in your project configuration. Refer to the dependencies section.


    • Couchbase Java SDK version 3.0.5 or later.

    • Java Couchbase Encryption version 3.0.0 or later.

    Maven Coordinates


    See the GitHub repository tags for the latest version.

    Optional Dependencies

    To reduce the footprint of this library, some of its dependencies are optional. Using certain features requires adding additional dependencies to your project.

    HashiCorp Vault Transit integration requires Spring Vault:



    To enable Field-Level Encryption, supply a CryptoManager when configuring the Java SDK’s ClusterEnvironment.

    KeyStore javaKeyStore = KeyStore.getInstance("MyKeyStoreType");
    FileInputStream fis = new"keyStoreName");
    char[] password = { 'a', 'b', 'c' };
    javaKeyStore.load(fis, password);
    Keyring keyring = new KeyStoreKeyring(javaKeyStore, keyName -> "swordfish");
    // AES-256 authenticated with HMAC SHA-512. Requires a 64-byte key.
    AeadAes256CbcHmacSha512Provider provider = AeadAes256CbcHmacSha512Provider.builder().keyring(keyring).build();
    CryptoManager cryptoManager = DefaultCryptoManager.builder().decrypter(provider.decrypter())
    ClusterEnvironment env = ClusterEnvironment.builder().cryptoManager(cryptoManager).build();
    Cluster cluster = Cluster.connect("localhost",
        ClusterOptions.clusterOptions("username", "password").environment(env));


    Two modes of operation are available:

    • Transparent encryption/decryption during Jackson data binding.

    • Manual field editing using JsonObjectCrypto.

    Data Binding Example

    Sensitive fields of your data classes can be annotated with @Encrypted. Let’s use this class as an example:

    public class Employee {
      private boolean replicant;
      // alternatively you could annotate the getter or setter
      public boolean isReplicant() {
        return replicant;
      public void setReplicant(boolean replicant) {
        this.replicant = replicant;

    Now let’s create an employee record and save it to Couchbase:

    Collection collection = cluster.bucket("myBucket").defaultCollection();
    Employee employee = new Employee();
    collection.upsert("employee:1234", employee); // encrypts the "replicant" field

    You can get the document as a JsonObject to verify the field was encrypted:

    JsonObject encrypted = collection.get("employee:1234").contentAsObject(); // does not decrypt anything

    Because contentAsObject() does not decrypt anything, the expected output is something like:

      "encrypted$replicant": {
        "alg": "AEAD_AES_256_CBC_HMAC_SHA512",
        "ciphertext": "xwcxyUyZ.....",
        "kid": "myKey"

    Now let’s read the employee record using data binding:

    Employee readItBack = collection.get("employee:1234").contentAs(Employee.class); // decrypts the "replicant" field

    This prints true.

    Using a custom ObjectMapper

    The code that enables encryption/decryption during data binding is packaged as a Jackson module called EncryptionModule. You can register this module with any Jackson ObjectMapper.

    You’ll need to do this if you want to supply your own customized ObjectMapper for the Java SDK to use when serializing documents. Here’s how to configure the cluster environment to use a custom JSON serializer backed by your own ObjectMapper with support for Field-Level Encryption:

    // CryptoManager cryptoManager = createMyCryptoManager();
    KeyStore javaKeyStore = KeyStore.getInstance("MyKeyStoreType");
    FileInputStream fis = new"keyStoreName");
    char[] ksPassword = { 'a', 'b', 'c' };
    javaKeyStore.load(fis, ksPassword);
    Keyring keyring = new KeyStoreKeyring(javaKeyStore, keyName -> "swordfish");
    // AES-256 authenticated with HMAC SHA-512. Requires a 64-byte key.
    AeadAes256CbcHmacSha512Provider provider = AeadAes256CbcHmacSha512Provider.builder().keyring(keyring).build();
    CryptoManager cryptoManager = DefaultCryptoManager.builder().decrypter(provider.decrypter())
    ObjectMapper mapper = new ObjectMapper();
    mapper.registerModule(new JsonValueModule()); // for JsonObject
    mapper.registerModule(new EncryptionModule(cryptoManager));
    // Here you can register more modules, add mixins, enable features, etc.
    ClusterEnvironment env = ClusterEnvironment.builder().cryptoManager(cryptoManager)
    Cluster cluster = Cluster.connect(connectionString,
        ClusterOptions.clusterOptions(username, password).environment(env));


    If you need more control of which fields get decrypted, or if you prefer working with the Couchbase JsonObject tree model, you can use a JsonObjectCrypto instance to read and write encrypted field values of a JsonObject.

    Collection collection = cluster.bucket("myBucket").defaultCollection();
    JsonObject document = JsonObject.create();
    JsonObjectCrypto crypto = document.crypto(collection);
    crypto.put("locationOfBuriedTreasure", "Between palm trees");
    // This displays the encrypted form of the field
    collection.upsert("treasureMap", document);
    JsonObject readItBack = collection.get("treasureMap").contentAsObject();
    JsonObjectCrypto readItBackCrypto = crypto.withObject(readItBack);

    Creating Encryption Keys

    The AEAD_AES_256_CBC_HMAC_SHA512 algorithm included in this library uses encryption keys that are 64 bytes long.

    Here’s an example that shows how to create a Java key store file containing a suitable encryption key:

    KeyStore keyStore = KeyStore.getInstance("JCEKS");
    keyStore.load(null); // initialize new empty key store
    // Generate 64 random bytes
    SecureRandom random = new SecureRandom();
    byte[] keyBytes = new byte[64];
    // Add a new key called "my-key" to the key store
    KeyStoreKeyring.setSecretKey(keyStore, "my-key", keyBytes, "protection-password".toCharArray());
    // Write the key store to disk
    try (OutputStream os = new FileOutputStream("MyKeystoreFile.jceks")) {, "integrity-password".toCharArray());

    And here’s how to use that file to create a Keyring for use with Couchbase Field-Level Encryption:

    KeyStore keyStore = KeyStore.getInstance("JCEKS");
    try (InputStream is = new FileInputStream("MyKeystoreFile.jceks")) {
      keyStore.load(is, "integrity-password".toCharArray());
    KeyStoreKeyring keyring = new KeyStoreKeyring(keyStore, keyName -> "protection-password");

    Migrating from SDK 2

    SDK 2 cannot read fields encrypted by SDK 3.

    It’s inadvisable to have both the old and new versions of your application active at the same time. The simplest way to migrate is to do an offline upgrade during a scheduled a maintenance window. For an online upgrade without downtime, consider a blue-green deployment.

    SDK 3 requires additional configuration to read fields encrypted by SDK 2. The rest of this section describes how to configure Field-Level Encryption in SDK 3 for backwards compatibility with SDK 2.

    Changing the field name prefix

    In SDK 2, the default prefix for encrypted field names was __crypt_. This caused problems for Couchbase Sync Gateway, which does not like field names to begin with an underscore. In SDK 3, the default prefix is encrypted$.

    For compatibility with SDK 2, you can configure the CryptoManager to use the old __crypt_ prefix:

    CryptoManager cryptoManager = DefaultCryptoManager.builder().encryptedFieldNamePrefix("__crypt_")
        // other config...
    In SDK 2, only top-level fields could be encrypted. SDK 3 allows encrypting fields at any depth. If you decide to rename the existing fields, make sure to do so before writing any encrypted fields below the top level, otherwise it may be difficult to rename the nested fields using a generic N1QL statement.

    Enabling decrypters for legacy algorithms

    The encryption algorithms used by SDK 2 are deprecated, and are no longer used for encrypting new data. To enable decrypting fields written by SDK 2, register the legacy decrypters when configuring the CryptoManager:

    CryptoManager cryptoManager = DefaultCryptoManager.builder()
        .legacyAesDecrypters(keyring, encryptionKeyName -> "MySigningKeyName")
        .legacyRsaDecrypter(keyring, publicKeyName -> "MyPrivateKeyName")
        // other config...
    The legacy decrypters require a mapping function. For AES, this function accepts an encryption key name and returns the corresponding signing key name. For RSA, this function accepts a public key name and returns the corresponding private key name.