Field Level Encryption

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

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

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]”,
	“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 object that comes after a key in a JSON document.

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

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 encrytpion 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.