Couchbase Lite C
Couchbase Lite C API
Typedefs | Functions | Variables
Encryptables

A CBLEncryptable is a value to be encrypted by the replicator when a document is pushed to the remote server. More...

Typedefs

typedef struct CBLEncryptable CBLEncryptable
 An encryptable value. More...
 

Functions

static const CBLEncryptableCBLEncryptable_Retain (const CBLEncryptable *t)
 
static void CBLEncryptable_Release (const CBLEncryptable *t)
 
CBLEncryptableCBLEncryptable_CreateWithNull (void)
 Creates CBLEncryptable object with null value. More...
 
CBLEncryptableCBLEncryptable_CreateWithBool (bool value)
 Creates CBLEncryptable object with a boolean value. More...
 
CBLEncryptableCBLEncryptable_CreateWithInt (int64_t value)
 Creates CBLEncryptable object with an int value. More...
 
CBLEncryptableCBLEncryptable_CreateWithUInt (uint64_t value)
 Creates CBLEncryptable object with an unsigned int value. More...
 
CBLEncryptableCBLEncryptable_CreateWithFloat (float value)
 Creates CBLEncryptable object with a float value. More...
 
CBLEncryptableCBLEncryptable_CreateWithDouble (double value)
 Creates CBLEncryptable object with a double value. More...
 
CBLEncryptableCBLEncryptable_CreateWithString (FLString value)
 Creates CBLEncryptable object with a string value. More...
 
CBLEncryptableCBLEncryptable_CreateWithValue (FLValue value)
 Creates CBLEncryptable object with an FLValue value. More...
 
CBLEncryptableCBLEncryptable_CreateWithArray (FLArray value)
 Creates CBLEncryptable object with an FLArray value. More...
 
CBLEncryptableCBLEncryptable_CreateWithDict (FLDict value)
 Creates CBLEncryptable object with an FLDict value. More...
 
FLValue CBLEncryptable_Value (const CBLEncryptable *encryptable)
 Returns the value to be encrypted by the push replicator. More...
 
FLDict CBLEncryptable_Properties (const CBLEncryptable *encryptable)
 Returns the dictionary format of the CBLEncryptable object. More...
 
bool FLDict_IsEncryptableValue (FLDict _cbl_nullable)
 Checks whether the given dictionary is a CBLEncryptable or not. More...
 
static bool FLValue_IsEncryptableValue (FLValue _cbl_nullable value)
 Checks whether the given FLValue is a CBLEncryptable or not. More...
 
const CBLEncryptable *_cbl_nullable FLDict_GetEncryptableValue (FLDict _cbl_nullable encryptableDict)
 Returns a CBLEncryptable object corresponding to the given encryptable dictionary in a document or NULL if the dictionary is not a CBLEncryptable. More...
 
static const CBLEncryptable *_cbl_nullable FLValue_GetEncryptableValue (FLValue _cbl_nullable value)
 Returns a CBLEncryptable object corresponding to the given Fleece Values in a document or NULL if the value is not a CBLEncryptable. More...
 
void FLSlot_SetEncryptableValue (FLSlot slot, const CBLEncryptable *encryptable)
 Set a CBLEncryptable's dictionary into a mutable dictionary's slot. More...
 
static void FLMutableDict_SetEncryptableValue (FLMutableDict dict, FLString key, CBLEncryptable *encryptable)
 Set a CBLEncryptable's dictionary into a mutable dictionary. More...
 

Variables

CBL_PUBLIC const FLSlice kCBLEncryptableType
 "encryptable" More...
 
CBL_PUBLIC const FLSlice kCBLEncryptableValueProperty
 "value" More...
 

Detailed Description

A CBLEncryptable is a value to be encrypted by the replicator when a document is pushed to the remote server.

When a document is pulled from the remote server, the encrypted value will be decrypted by the replicator.

Similar to CBLBlob, a CBLEncryptable acts as a proxy for a dictionary structure with the special marker property "@type":"encryptable", and another property value whose value is the actual value to be encrypted by the push replicator.

The push replicator will automatically detect CBLEncryptable dictionaries inside the document and calls the specified CBLPropertyEncryptor callback to encrypt the actual value. When the value is successfully encrypted, the replicator will transform the property key and the encrypted CBLPropertyEncryptor dictionary value into Couchbase Server SDK's encrypted field format :

The original key will be prefixed with 'encrypted$'.

The transformed CBLEncryptable dictionary will contain alg property indicating the encryption algorithm, ciphertext property whose value is a base-64 string of the encrypted value, and optionally kid property indicating the encryption key identifier if specified when returning the result of CBLPropertyEncryptor callback call.

For security reason, a document that contains CBLEncryptable dictionaries will fail to push with the kCBLErrorCrypto error if their value cannot be encrypted including when a CBLPropertyEncryptor callback is not specified or when there is an error or a null result returned from the callback call.

The pull replicator will automatically detect the encrypted properties that are in the Couchbase Server SDK's encrypted field format and call the specified CBLPropertyDecryptor callback to decrypt the encrypted value. When the value is successfully decrypted, the replicator will transform the property format back to the CBLEncryptable format including removing the 'encrypted$' prefix.

The CBLPropertyDecryptor callback can intentionally skip the decryption by returnning a null result. When a decryption is skipped, the encrypted property in the form of Couchbase Server SDK's encrypted field format will be kept as it was received from the remote server. If an error is returned from the callback call, the document will be failed to pull with the kCBLErrorCrypto error.

If a CBLPropertyDecryptor callback is not specified, the replicator will not attempt to detect any encrypted properties. As a result, all encrypted properties in the form of Couchbase Server SDK's encrypted field format will be kept as they was received from the remote server.

To create a new CBLEncryptable, call CBLEncryptable_CreateWith<Value Type> function such as CBLEncryptable_CreateWithString. Then call FLSlot_SetEncryptableValue to add the CBLEncryptable to a dictionary in the document. Noted that adding CBLEncryptable to an array is not supported. For example:

FLSlot_SetEncryptableValue(FLMutableDict_Set(properties, key), encryptableValue);

Note: When creating a CBLEncryptable, you are responsible for releasing the CBLEncryptable object but not until its document is saved into the database.

When a document is loaded from the database, call FLDict_GetEncryptableValue on an Encryptable dictionary value to obtain a CBLEncryptable object.

Typedef Documentation

◆ CBLEncryptable

An encryptable value.

The encryptable values will be encrypted by a push replicator via the specified property encryptor callback when the document is push to the remote server. Likewise, the encryptable values will be decrypted by a pull replicator via the specified property decryptor callback when the document is pulled from the remote server.

Function Documentation

◆ CBLEncryptable_CreateWithArray()

CBLEncryptable * CBLEncryptable_CreateWithArray ( FLArray  value)

Creates CBLEncryptable object with an FLArray value.

◆ CBLEncryptable_CreateWithBool()

CBLEncryptable * CBLEncryptable_CreateWithBool ( bool  value)

Creates CBLEncryptable object with a boolean value.

◆ CBLEncryptable_CreateWithDict()

CBLEncryptable * CBLEncryptable_CreateWithDict ( FLDict  value)

Creates CBLEncryptable object with an FLDict value.

◆ CBLEncryptable_CreateWithDouble()

CBLEncryptable * CBLEncryptable_CreateWithDouble ( double  value)

Creates CBLEncryptable object with a double value.

◆ CBLEncryptable_CreateWithFloat()

CBLEncryptable * CBLEncryptable_CreateWithFloat ( float  value)

Creates CBLEncryptable object with a float value.

◆ CBLEncryptable_CreateWithInt()

CBLEncryptable * CBLEncryptable_CreateWithInt ( int64_t  value)

Creates CBLEncryptable object with an int value.

◆ CBLEncryptable_CreateWithNull()

CBLEncryptable * CBLEncryptable_CreateWithNull ( void  )

Creates CBLEncryptable object with null value.

◆ CBLEncryptable_CreateWithString()

CBLEncryptable * CBLEncryptable_CreateWithString ( FLString  value)

Creates CBLEncryptable object with a string value.

◆ CBLEncryptable_CreateWithUInt()

CBLEncryptable * CBLEncryptable_CreateWithUInt ( uint64_t  value)

Creates CBLEncryptable object with an unsigned int value.

◆ CBLEncryptable_CreateWithValue()

CBLEncryptable * CBLEncryptable_CreateWithValue ( FLValue  value)

Creates CBLEncryptable object with an FLValue value.

◆ CBLEncryptable_Properties()

FLDict CBLEncryptable_Properties ( const CBLEncryptable encryptable)

Returns the dictionary format of the CBLEncryptable object.

◆ CBLEncryptable_Release()

static void CBLEncryptable_Release ( const CBLEncryptable t)
inlinestatic

◆ CBLEncryptable_Retain()

static const CBLEncryptable * CBLEncryptable_Retain ( const CBLEncryptable t)
inlinestatic

◆ CBLEncryptable_Value()

FLValue CBLEncryptable_Value ( const CBLEncryptable encryptable)

Returns the value to be encrypted by the push replicator.

◆ FLDict_GetEncryptableValue()

const CBLEncryptable *_cbl_nullable FLDict_GetEncryptableValue ( FLDict _cbl_nullable  encryptableDict)

Returns a CBLEncryptable object corresponding to the given encryptable dictionary in a document or NULL if the dictionary is not a CBLEncryptable.

Note
The returned CBLEncryptable object will be released when its document is released.

◆ FLDict_IsEncryptableValue()

bool FLDict_IsEncryptableValue ( FLDict  _cbl_nullable)

Checks whether the given dictionary is a CBLEncryptable or not.

◆ FLMutableDict_SetEncryptableValue()

static void FLMutableDict_SetEncryptableValue ( FLMutableDict  dict,
FLString  key,
CBLEncryptable encryptable 
)
inlinestatic

Set a CBLEncryptable's dictionary into a mutable dictionary.

◆ FLSlot_SetEncryptableValue()

void FLSlot_SetEncryptableValue ( FLSlot  slot,
const CBLEncryptable encryptable 
)

Set a CBLEncryptable's dictionary into a mutable dictionary's slot.

◆ FLValue_GetEncryptableValue()

static const CBLEncryptable *_cbl_nullable FLValue_GetEncryptableValue ( FLValue _cbl_nullable  value)
inlinestatic

Returns a CBLEncryptable object corresponding to the given Fleece Values in a document or NULL if the value is not a CBLEncryptable.

Note
The returned CBLEncryptable object will be released when its document is released.

◆ FLValue_IsEncryptableValue()

static bool FLValue_IsEncryptableValue ( FLValue _cbl_nullable  value)
inlinestatic

Checks whether the given FLValue is a CBLEncryptable or not.

Variable Documentation

◆ kCBLEncryptableType

CBL_PUBLIC const FLSlice kCBLEncryptableType
extern

"encryptable"

◆ kCBLEncryptableValueProperty

CBL_PUBLIC const FLSlice kCBLEncryptableValueProperty
extern

"value"