Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

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.
    This is a developer preview release of Field Level Encryption for the 3.0 API version of Couchbase Java SDK. As such, it is unsupported, and this documentation may lag behind development changes. Refer to the GitHub repo for the latest updates.

    Overview

    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

    From Couchbase Server 5.5, AES-256, AES-128, and RSA were all supported in earlier versions of the SDK’s Field Level Encryption library — these encryption algorithms are now deprecated, but decryption of data encrypted under earlier versions continues to be supported. SDK 3 uses a new algorithm, AEAD_AES_256_CBC_HMAC_SHA_512, which bundles the auth key and the encryption key into a single 64-byte "fat key". The key materials used by the AES and HMAC algorithms are distinct, but the keys can be managed as a single unit.

    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]”,
	“Iv” : [“INITIALIZATION_VECTOR”]
}

    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

    string

    "magicWord":"xyzzy"

    "xyzzy"

    object

    "score":{"dance":10,"presentation":3}

    {"dance":10,"presentation":3}

    numeric

    "myint":10

    10

    null

    "isnull":null

    null

    array

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

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

    boolean

    "dues_paid":true

    true

    Auditing

    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.

    Packaging

    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.