Couchbase C Client  2.9.4
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.

Functions

void lcbcrypto_register (lcb_t instance, const char *name, lcbcrypto_PROVIDER *provider)
 Register crypto-provider for specified alias. More...
 
void lcbcrypto_unregister (lcb_t instance, const char *name)
 Unregister crypto-provider for specified alias. More...
 
void lcbcrypto_ref (lcbcrypto_PROVIDER *provider)
 Increment reference counter for crypto-provider. More...
 
void lcbcrypto_unref (lcbcrypto_PROVIDER *provider)
 Decrement reference counter for crypto-provider. More...
 
lcb_error_t lcbcrypto_encrypt_fields (lcb_t instance, lcbcrypto_CMDENCRYPT *cmd)
 
Encrypt all specified fields in the JSON encoded object. More...
 
lcb_error_t lcbcrypto_decrypt_fields (lcb_t instance, lcbcrypto_CMDDECRYPT *cmd)
 
Decrypt all specified fields in the JSON encoded object. More...
 

Macros

#define LCBCRYPTO_DEFAULT_FIELD_PREFIX
 Default prefix for encrypted JSON fields.
 

Function Documentation

◆ lcbcrypto_register()

void lcbcrypto_register ( lcb_t  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);
Examples:
example/crypto/openssl_symmetric_decrypt.c, and example/crypto/openssl_symmetric_encrypt.c.

◆ lcbcrypto_unregister()

void lcbcrypto_unregister ( lcb_t  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_error_t lcbcrypto_encrypt_fields ( lcb_t  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);
Stability
Committed:
Examples:
example/crypto/openssl_symmetric_encrypt.c.

◆ lcbcrypto_decrypt_fields()

lcb_error_t lcbcrypto_decrypt_fields ( lcb_t  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);
Stability
Committed:
Examples:
example/crypto/openssl_symmetric_decrypt.c.

Data Structure Documentation

◆ lcbcrypto_SIGV

struct lcbcrypto_SIGV


IOV-style structure for signing functions of crypto-provider.

Stability
Committed:
Examples:
example/crypto/openssl_symmetric_provider.c.
Data Fields
const uint8_t * data pointer to data
size_t len length of the data in bytes

◆ lcbcrypto_PROVIDER

struct lcbcrypto_PROVIDER

Data Fields

uint16_t version
 version of the structure, current value is 1
 
int16_t _refcnt
 reference counter
 
uint64_t flags
 provider-specific flags
 
void * cookie
 opaque pointer (e.g. More...
 
void(* destructor )(struct lcbcrypto_PROVIDER *provider)
 destructor function, or NULL
 
union {
   struct {
void(* release_bytes )(struct lcbcrypto_PROVIDER *provider, void *bytes)
 function to use when the library wants to deallocate memory, returned by provider
 
lcb_error_t(* generate_iv )(struct lcbcrypto_PROVIDER *provider, uint8_t **iv, size_t *iv_len)
 initialization vector (IV) generator
 
lcb_error_t(* sign )(struct lcbcrypto_PROVIDER *provider, const lcbcrypto_SIGV *inputs, size_t input_num, uint8_t **sig, size_t *sig_len)
 generate cryptographic signature for the data
 
lcb_error_t(* verify_signature )(struct lcbcrypto_PROVIDER *provider, const lcbcrypto_SIGV *inputs, size_t input_num, uint8_t *sig, size_t sig_len)
 verify signature of the data
 
lcb_error_t(* encrypt )(struct lcbcrypto_PROVIDER *provider, const uint8_t *input, size_t input_len, const uint8_t *iv, size_t iv_len, uint8_t **output, size_t *output_len)
 encrypt data
 
lcb_error_t(* decrypt )(struct lcbcrypto_PROVIDER *provider, const uint8_t *input, size_t input_len, const uint8_t *iv, size_t iv_len, uint8_t **output, size_t *output_len)
 decrypt data
 
const char *(* get_key_id )(struct lcbcrypto_PROVIDER *provider)
 returns key identifier, associated with the crypto-provider
 
   } v1
 
v
 

Field Documentation

◆ cookie

void* cookie

opaque pointer (e.g.

pointer to wrapper instance)

◆ lcbcrypto_FIELDSPEC

struct lcbcrypto_FIELDSPEC


Structure for JSON field specification for encrypt/decrypt API.

See also
lcbcrypto_encrypt_fields
lcbcrypto_decrypt_fields
Stability
Committed:
Examples:
example/crypto/openssl_symmetric_decrypt.c, and example/crypto/openssl_symmetric_encrypt.c.

Public Member Functions

 LCB_DEPRECATED2 (const char *kid, "Do not use kid field. Encryption keys have to be part of the provider implementation")
 

Data Fields

const char * name
 field name (NUL-terminated)
 
const char * alg
 crypto provider alias (NUL-terminated)
 

◆ lcbcrypto_CMDENCRYPT

struct lcbcrypto_CMDENCRYPT


Command to encrypt JSON fields.

See also
lcbcrypto_encrypt_fields
Stability
Committed:
Examples:
example/crypto/openssl_symmetric_encrypt.c.
Data Fields
uint16_t version version of the structure, currently valid value is 0
const char * prefix prefix to encrypted field.

When NULL, it will use LCBCRYPTO_DEFAULT_FIELD_PREFIX

const char * doc pointer to the input JSON document
size_t ndoc size of the input JSON document
char * out pointer to output JSON document.

When no changes were applied, this field will be set to NULL

size_t nout size of the output JSON document
lcbcrypto_FIELDSPEC * fields list of field specs
size_t nfields number of field specs

◆ lcbcrypto_CMDDECRYPT

struct lcbcrypto_CMDDECRYPT


Command to decrypt JSON fields.

See also
lcbcrypto_decrypt_fields
Stability
Committed:
Examples:
example/crypto/openssl_symmetric_decrypt.c.
Data Fields
uint16_t version version of the structure, currently valid value is 0
const char * prefix prefix to encrypted field.

When NULL, it will use LCBCRYPTO_DEFAULT_FIELD_PREFIX

const char * doc pointer to the input JSON document
size_t ndoc size of the input JSON document
char * out pointer to output JSON document.

When no changes were applied, this field will be set to NULL

size_t nout size of the output JSON document
lcbcrypto_FIELDSPEC * fields list of field specs
size_t nfields number of field specs