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

instance	the handle
name	provider alias, this will be recorded in JSON.
provider	implementation 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_INSTANCE *	instance,
		const char *	name )

Unregister crypto-provider for specified alias.

See full example in example/crypto/openssl_symmetric_provider.c

Parameters

instance	the handle
name	provider alias.

lcbcrypto_ref()

void lcbcrypto_ref

(

lcbcrypto_PROVIDER *

provider

)

Increment reference counter for crypto-provider.

Parameters

provider

provider 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

provider

provider 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

instance	the handle
cmd	the 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"

lcbcrypto_CMDENCRYPT cmd = {};
lcbcrypto_FIELDSPEC field = {};
lcb_STATUS err;
 
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_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

instance	the handle
cmd	the 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"

lcbcrypto_CMDDECRYPT cmd = {};
lcbcrypto_FIELDSPEC field = {};
lcb_STATUS err;
 
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

Crypto-provider interface.

See full example in example/crypto/openssl_symmetric_provider.c

See also

lcbcrypto_register

lcbcrypto_unregister

Stability

Committed

Examples

example/crypto/openssl_symmetric_provider.c.

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. pointer to wrapper instance)
void(*)(struct lcbcrypto_PROVIDER *provider)	destructor	destructor function, or NULL
union lcbcrypto_PROVIDER.v	v

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