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 CBLEncryptable *	CBLEncryptable_Retain (const CBLEncryptable *t)
static void	CBLEncryptable_Release (const CBLEncryptable *t)
CBLEncryptable *	CBLEncryptable_CreateWithNull (void)
	Creates CBLEncryptable object with null value. More...
CBLEncryptable *	CBLEncryptable_CreateWithBool (bool value)
	Creates CBLEncryptable object with a boolean value. More...
CBLEncryptable *	CBLEncryptable_CreateWithInt (int64_t value)
	Creates CBLEncryptable object with an int value. More...
CBLEncryptable *	CBLEncryptable_CreateWithUInt (uint64_t value)
	Creates CBLEncryptable object with an unsigned int value. More...
CBLEncryptable *	CBLEncryptable_CreateWithFloat (float value)
	Creates CBLEncryptable object with a float value. More...
CBLEncryptable *	CBLEncryptable_CreateWithDouble (double value)
	Creates CBLEncryptable object with a double value. More...
CBLEncryptable *	CBLEncryptable_CreateWithString (FLString value)
	Creates CBLEncryptable object with a string value. More...
CBLEncryptable *	CBLEncryptable_CreateWithValue (FLValue value)
	Creates CBLEncryptable object with an FLValue value. More...
CBLEncryptable *	CBLEncryptable_CreateWithArray (FLArray value)
	Creates CBLEncryptable object with an FLArray value. More...
CBLEncryptable *	CBLEncryptable_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

typedef struct CBLEncryptable 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"