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_INSTANCE *instance, const char *name, lcbcrypto_PROVIDER *provider)
	Register crypto-provider for specified alias. More...
void	lcbcrypto_unregister (lcb_INSTANCE *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_STATUS	lcbcrypto_encrypt_fields (lcb_INSTANCE *instance, lcbcrypto_CMDENCRYPT *cmd)
	Encrypt all specified fields in the JSON encoded object. More...
lcb_STATUS	lcbcrypto_decrypt_fields (lcb_INSTANCE *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_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. 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_STATUS(*	generate_iv )(struct lcbcrypto_PROVIDER *provider, uint8_t **iv, size_t *iv_len)
	initialization vector (IV) generator
lcb_STATUS(*	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_STATUS(*	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_STATUS(*	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_STATUS(*	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