Couchbase C Client  3.3.15
Asynchronous C Client for Couchbase
Encryption

Detailed Description

Register crypto-providers and working with encrypted fields of the documents.

These routines contain functionality to define and hook crypto providers, as well as functions which should be used for portable (cross SDK) encoding of encrypted fields.

Function Documentation

◆ lcbcrypto_register()

void lcbcrypto_register ( lcb_INSTANCE * instance,
const char * name,
lcbcrypto_PROVIDER * provider )

Register crypto-provider for specified alias.

See full example in example/crypto/openssl_symmetric_provider.c

Parameters
instancethe handle
nameprovider alias, this will be recorded in JSON.
providerimplementation of the crypto-provider
Register provider as "AES-256-HMAC-SHA256".
lcbcrypto_PROVIDER *provider = calloc(1, sizeof(lcbcrypto_PROVIDER));
provider->version = 1;
provider->destructor = osp_free;
provider->v.v1.release_bytes = osp_release_bytes;
provider->v.v1.generate_iv = osp_generate_iv;
provider->v.v1.sign = osp_sign;
provider->v.v1.verify_signature = osp_verify_signature;
provider->v.v1.encrypt = osp_encrypt;
provider->v.v1.decrypt = osp_decrypt;
provider->v.v1.get_key_id = osp_get_key_id;
lcbcrypto_register(instance, "AES-256-HMAC-SHA256", provider);
void(* destructor)(struct lcbcrypto_PROVIDER *provider)
destructor function, or NULL
Definition crypto.h:72
uint16_t version
version of the structure, current value is 1
Definition crypto.h:68
void lcbcrypto_register(lcb_INSTANCE *instance, const char *name, lcbcrypto_PROVIDER *provider)
Register crypto-provider for specified alias.
Crypto-provider interface.
Definition crypto.h:67
Examples
example/crypto/openssl_symmetric_decrypt.c, and example/crypto/openssl_symmetric_encrypt.c.

◆ lcbcrypto_unregister()

void lcbcrypto_unregister ( lcb_INSTANCE * instance,
const char * name )

Unregister crypto-provider for specified alias.

See full example in example/crypto/openssl_symmetric_provider.c

Parameters
instancethe handle
nameprovider alias.

◆ lcbcrypto_ref()

void lcbcrypto_ref ( lcbcrypto_PROVIDER * provider)

Increment reference counter for crypto-provider.

Parameters
providerprovider instance

◆ lcbcrypto_unref()

void lcbcrypto_unref ( lcbcrypto_PROVIDER * provider)

Decrement reference counter for crypto-provider.

It calls destructor once counter reaches zero. The provider instance should not be used after calling this function.

Parameters
providerprovider instance

◆ lcbcrypto_encrypt_fields()

lcb_STATUS lcbcrypto_encrypt_fields ( lcb_INSTANCE * instance,
lcbcrypto_CMDENCRYPT * cmd )

Encrypt all specified fields in the JSON encoded object.

The function will remove original content of the field, and rename it using LCBCRYPTO_DEFAULT_FIELD_PREFIX, or custom prefix, specified in the command.

See full example in example/crypto/openssl_symmetric_encrypt.c

Parameters
instancethe handle
cmdthe command structure
Returns
LCB_SUCCESS if successful, an error code otherwise
Encrypt field "message" in the document using provider registered as "AES-256-HMAC-SHA256"
cmd.version = 0;
cmd.prefix = NULL;
cmd.doc = "{\"message\":\"hello world\"}";
cmd.ndoc = strlen(cmd.doc);
cmd.nfields = 1;
cmd.fields = &field;
field.name = "message";
field.alg = "AES-256-HMAC-SHA256";
err = lcbcrypto_encrypt_fields(instance, &cmd);
lcbcrypto_FIELDSPEC * fields
list of field specs
Definition crypto.h:125
size_t ndoc
size of the input JSON document
Definition crypto.h:122
const char * doc
pointer to the input JSON document
Definition crypto.h:121
const char * prefix
prefix to encrypted field.
Definition crypto.h:120
const char * name
field name (NUL-terminated)
Definition crypto.h:106
const char * alg
crypto provider alias (NUL-terminated)
Definition crypto.h:107
size_t nfields
number of field specs
Definition crypto.h:126
lcb_STATUS lcbcrypto_encrypt_fields(lcb_INSTANCE *instance, lcbcrypto_CMDENCRYPT *cmd)
Encrypt all specified fields in the JSON encoded object.
Command to encrypt JSON fields.
Definition crypto.h:118
Structure for JSON field specification for encrypt/decrypt API.
Definition crypto.h:105
lcb_STATUS
Error codes returned by the library.
Definition error.h:213
Stability
Committed
Examples
example/crypto/openssl_symmetric_encrypt.c.

◆ lcbcrypto_decrypt_fields()

lcb_STATUS lcbcrypto_decrypt_fields ( lcb_INSTANCE * instance,
lcbcrypto_CMDDECRYPT * cmd )

Decrypt all specified fields in the JSON encoded object.

The function will remove original content of the field, and rename it using LCBCRYPTO_DEFAULT_FIELD_PREFIX, or custom prefix, specified in the command.

See full example in example/crypto/openssl_symmetric_decrypt.c

Parameters
instancethe handle
cmdthe command structure
Returns
LCB_SUCCESS if successful, an error code otherwise
Decrypt field "message" in the document using provider registered as "AES-256-HMAC-SHA256"
cmd.version = 0;
cmd.prefix = NULL;
cmd.doc = "{\"__crypt_message\":{" \
"\"alg\":\"AES-256-HMAC-SHA256\"," \
"\"ciphertext\":\"gYuyEhf6S0AiMGZJZZV35Q==\"," \
"\"iv\":\"ZedmvjWy0lIrLn6OmQmNqQ==\"," \
"\"kid\":\"mykeyid\"," \
"\"sig\":\"FgleInW3Iia04XqLbm5Hd3qVoa77Ocs7g2x4pOutEtY=\"}" \
"}";
cmd.ndoc = strlen(cmd.doc);
cmd.nfields = 1;
cmd.fields = &field;
field.name = "message";
field.alg = "AES-256-HMAC-SHA256";
err = lcbcrypto_decrypt_fields(instance, &cmd);
lcb_STATUS lcbcrypto_decrypt_fields(lcb_INSTANCE *instance, lcbcrypto_CMDDECRYPT *cmd)
Decrypt all specified fields in the JSON encoded object.
Command to decrypt JSON fields.
Definition crypto.h:135
Stability
Committed
Examples
example/crypto/openssl_symmetric_decrypt.c.

Data Structure Documentation

◆ lcbcrypto_SIGV

struct lcbcrypto_SIGV

◆ lcbcrypto_PROVIDER

struct lcbcrypto_PROVIDER

◆ lcbcrypto_FIELDSPEC

struct lcbcrypto_FIELDSPEC

◆ lcbcrypto_CMDENCRYPT

struct lcbcrypto_CMDENCRYPT

◆ lcbcrypto_CMDDECRYPT

struct lcbcrypto_CMDDECRYPT