A newer version of this documentation is available.

View Latest

Field Level Encryption

    Fields within a document can be securely encrypted by the SDK, to support FIPS-140-2 compliance.


    field level encryption architecture
    Figure 1. Actors & Responsibilities in Field Level Encryption

    This is a client-side implementation, with key management and initialization of data encryption done during configuration of the SDK, which then exposes the API during runtime, for normal read/write operations.

    Algorithm and Key Store

    In Couchbase Data Platform 5.5, AES-256, AES-128, and RSA are all supported. Native Keystores (including Java Key Store and Windows Certificate Store) are supported, as well as an in-memory keystore for development and testing. More options for key stores and encryption algorithms may appear in future SDK releases.

    Here is an example of an in-memory store for development and testing called the “InsecureKeyStore”, to reflect its lack of security:

    public class InsecureKeyProvider : IKeyProvider
        private readonly Dictionary<string, string> _keys = new Dictionary<string, string>();
        public string GetKey(string keyname)
            return _keys[keyname];
        public void StoreKey(string keyname, string key)
            _keys[keyname] = key;

    The keys are stored by name in a dictionary and retrieved using the same name. See the sample code page for more secure code.

    Field Encryption Format

    Behind the API, the following format is used internally to encompass both the temporary field name used to hold the encrypted value, plus the additional metadata associated with the algorithm used and the public key:

    __[PREFIX]_[FIELDNAME]” : {
    	“kid” : “[KEY_IDENTIFIER]”,
    	“alg”: “[ALGORITHM”],
    	“ciphertext”: “[BASE64_ENCRYPTED_DATA]”,
    	“sig”: “[BASE64_HMAC_SIGNATURE]”,

    This is how Couchbase stores the JSON internally, but it is exposed to the developer as a public API. For your preferred SDK, an API reference is available, linked from Install and Start Using the Java SDK with Couchbase Server as well as sample code.

    Field Types

    The encryption payload can be any JSON type.

    Table 1. Supported Field Types
    Type Example Payload














    "myFruityArray":['Apple', 'Banana', 'Olive']

    ['Apple', 'Banana', 'Olive']





    For auditing purposes, the encrypted fields must be discoverable, for example via N1QL.

    Data Safeguards

    Under error conditions, to prevent data loss, an error in decryption or encryption in any part of an operation will cause the whole operation to fail with an exception, to prevent unnoticed loss of data.

    It’s important that encrypted fields be treated as “special” fields and not mutated by APIs other than through the Field Level Encryption (FLE) API. For example, for AES-HMAC-SHA256 the entire temporary field is signed; if any changes are made to any fields (“alg”, “kid”, “ciphertext”, “sig” or “iv”) then the decryption will fail because the signature has changed.


    Field Level Encryption for all SDKs is a separate package from the Couchbase SDK itself; the APIs are extensions of the SDK, but the SDK does not have a dependency on FLE. This means you can install the relevant SDK without being dependant upon a suite of crypto libraries.