You are viewing the documentation for a prerelease version.

Field Level Encryption

  • 3.0
  • beta Enterprise
    This is an Enterprise Edition feature.
    Community Edition
    • The push replicator will detect encryptable values inside a document. It will fail to replicate unencrypted encryptable values with a crypto error.

    • The pull replicator will not detect encryptable values inside pulled documents. The document will be saved as it was received. This may include Server SDK encrypted fields


    Couchbase Lite for C 3.0.0 (beta) supports client-side, field-Level encryption on replications, allowing applications to encrypt/decrypt sensitive fields in documents using an encryption framework of choice.

    Using the new client-side encryption capability, Couchbase Lite C applications can designate selected fields for encryption and have the client automatically handle the encryption and-or decryption at property level during the replication.

    Only clients with access to the correct encryption keys can decrypt and read the protected data.

    The client-side encryption is compatible with the Couchbase server SDK field-level encryption format — see, for example,

    Encryptable Type

    The API includes a CBLEncryptable type, representing an encryptable value to be automatically encrypted/decrypted the replicator — see Example 1.

    You declare properties requiring encryption by the replicator, as a dictionary with the structure shown in Example 1.

    Example 1. Encryptable-type Dictionary Structure
      "@type": "encryptable",
      “value” : <Decrypted Value>
    } (1)
      "@type": "encryptable",
      “ciphertext”: <Encrypted Value in BASE64 String>
    } (2)

    The key for the value can be either of the following:

    1 Use value as the key when storing a decrypted value, which can be any type (string, number, boolean, dictionary, array or null).
    2 Use cyphertext as the key when storing a encrypted value, which must be a BASE-64 String.

    Replicator Decryption

    Pull replication detects encryptable values before saving them to the local database and decrypts them using the property decryption callback function — see: Decryption for more on the decryption callback function.

    On successful decryption the replicator saves the property in encryptable dictionary format (removing the encrypted$ prefix) — see: Example 1.

    Replicator Encryption

    Push replication detects encryptable values before pushing them to the remote database and encrypts them using the property encryption callback function — see: Encryption.

    On successful encryption the replicator transforms the property into a format compatible with Couchbase Server SDK — see: Example 3.

    Server SDK compatibility

    Couchbase Lite’s replicator ensures compatibility with Server SDK’s field level. Both Push and Pull replication transform Couchbase Lite’s encryptable dictionary to-and-from Server SDK Encrypted Field dictionary structure — see: Example 3.

    Push replicator
    • Adds the prefix encrypted$ to the key.

    • Sets the SDK'` alg either to a user-specified algorithm name or the default CB_MOBILE_CUSTOM.

    • Set the value’s key as ciphertext

    • Stores the encrypted value as a BASE64 string.

      Example 2. Stored Encryptable
          “alg”: <User-Specified or CB_MOBILE_CUSTOM>,
          “ciphertext” : <Encrypted Value in BASE64 String>
    Pull replicator
    • Detects encrypted encryptable values by looking for dictionary keys prefixed with “encrypted$”.

    • Transforms the dictionary by:

      • Removing alg

      • Replacing the ciphertext key with the value

      • Storing the decrypted key/value in CBLEncryptable format

    Example 3. Server SDK Encrypted Field Structure

    Server SDK’s field (property) level encryption uses key mangling, by add a prefix to the field name (encrypted$). Its directory structure differs CBL’s encryptable dictionary when serializing the encrypted fields; as shown here.

        encrypted$mykey: {
            “alg” : “AEAD_AES_256_CBC_HMAC_SHA512”, (1)
            “kid” : “my-key-id”,
            “ciphertext”: “<BASE64-TEXT>”
    1 Here alg identifies the encryption algorithm and is the only required field.

    Callback Definition


    Provide an encryption callback function CBLPropertyEncryptor to encrypt encryptable properties during replication.

    After encryption the FLSliceResult is released and the returned value zeroed. See Example 4 for an example encryptor callback function.

    If you return a null slice the replicator will fail and log a crypto error message.


    Provide a decryption callback function CBLPropertyDecryptor to decrypt any encryptable properties. After decryption the FLSliceResult is released and the returned value zeroed. See Example 4 for an example decryptor callback function.

    If you return a null slice without an error the replicator skips and saves the property as received.

    If you return a null slice with an error the replicator logs the error and does not replicate the document.

    Example 4. Simple Encryption-Decryption Callback
    // Purpose: Declare property-level encryptor callback functions
    static FLSliceResult my_cipher_function(FLSlice input) {
        FLSliceResult result = FLSliceResult_New(input.size);
        for(int i = 0; i < input.size; ++i) {
            ((uint8_t*)(result.buf))[i] = ((uint8_t*)input.buf)[i] ^ 'K';}
        return result;
    static FLSliceResult property_encryptor(void* context, FLString docID, FLDict props, FLString path,
                                            FLSlice input, FLStringResult* algorithm, FLStringResult* keyID, CBLError* error) {
        *algorithm = FLSlice_Copy(FLSTR("MyEnc"));
        return my_cipher_function(input);
    static FLSliceResult property_decryptor(void* context, FLString documentID, FLDict properties, FLString keyPath,
                                            FLSlice input, FLString algorithm, FLString keyID, CBLError* error) {
        return my_cipher_function(input);

    Callback Configuration

    You register the callback function for use by declaring them in the replicator configuration using propertyEncryptor() and-or propertyDecryptor() — see: Example 5

    If you do not provide an encryption callback:

    • The push replicator always detects encrypted encryptable values in a document and will fail the document replication, flagging a crypto error.

    • The pull replicator does not detect encrypted encryptables in pulled documents and will save documents as received; this could include SDK encrypted field dictionaries.

    Example 5. Simple Callback Replicator Configuration

    Querying Encryptables

    Encrypted values can be queried — see Example 6. The query result of an encryptable value is CBLEncryptable

    CBLEncryptable exposes a value property for query purposes. If this value is encrypted the query will return MISSING.

    Example 6. A Simple encryptable Query
    SELECT  ssn,  (1)
            ssn.value  (2)
    FROM db WHERE ssn.value = "123-45-6789"
    1 The returned ssn column is in the form of an encryptable dictionary
    2 The returned ssn.value column is the actual value, unless it is still encrypted in which case it returns MISSING



    In the case of nested encryptable types, the replicator only encrypts the outer encryptable.


    For compatibility with Server SDKS, encryptables are not supported within arrays.

    The push replicator should detect and report an error if an encrypted property is found in an array.


    Encrypting blob’s content is not supported.

    Where a Blob as a Fleece dictionary is specified in the encrypted property value, only the dictionary is encrypted; not the blob’s content.

    Delta Sync

    Delta Sync will be disabled and a warning message logged when propertyEncryption is configured.