CryptoInterface.h File Reference

Abstract interface for crypto processing. More...

#include <stdint.h>
#include "BPSecLib_Private.h"
#include "BPSecLib_Public.h"

Include dependency graph for CryptoInterface.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	BSL_AuthCtx_t
	Struct def for HMAC operation context. More...
struct	BSL_Cipher_t
	Struct def for cipher operation context. More...

Macros
#define	BSL_CRYPTO_AESGCM_AUTH_TAG_LEN   (16)

Typedefs
typedef int(*	BSL_Crypto_RandBytesFn) (unsigned char *buf, int len)
	Function pointer def for random bytestring generator.

Enumerations
enum	BSL_CipherMode_e { BSL_CRYPTO_ENCRYPT , BSL_CRYPTO_DECRYPT }
	Enum def to define cipher contexts as encryption or decryption operations. More...
enum	BSL_CryptoCipherSHAVariant_e { BSL_CRYPTO_SHA_256 , BSL_CRYPTO_SHA_384 , BSL_CRYPTO_SHA_512 }
enum	BSL_CryptoCipherAESVariant_e { BSL_CRYPTO_AES_128 , BSL_CRYPTO_AES_256 }

Functions
void	BSL_CryptoInit (void)
	Initialize the crypto subsystem.
void	BSL_CryptoDeinit (void)
	Deinitialize the crypto subsystem.
void	BSL_Crypto_SetRngGenerator (BSL_Crypto_RandBytesFn rand_gen_fn)
	Set RNG generator to be used by crypto library.
BSL_REQUIRE_CHECK int	BSL_AuthCtx_Init (BSL_AuthCtx_t *hmac_ctx, const char *keyid, BSL_CryptoCipherSHAVariant_e sha_var)
	Initialize HMAC context resources and set private key and SHA variant.
BSL_REQUIRE_CHECK int	BSL_AuthCtx_DigestBuffer (BSL_AuthCtx_t *hmac_ctx, const void *data, size_t data_len)
	Input data to HMAC sign to context.
int	BSL_AuthCtx_DigestSeq (BSL_AuthCtx_t *hmac_ctx, BSL_SeqReader_t *reader)
	Input data to HMAC sign to context.
int	BSL_AuthCtx_Finalize (BSL_AuthCtx_t *hmac_ctx, void **hmac, size_t *hmac_len)
	Finalize HMAC tag.
int	BSL_AuthCtx_Deinit (BSL_AuthCtx_t *hmac_ctx)
	Deinitialize HMAC context resources.
int	BSL_Crypto_UnwrapKey (BSL_Data_t *unwrapped_key_output, BSL_Data_t wrapped_key_plaintext, const char *key_id, size_t aes_variant)
int	BSL_Crypto_WrapKey (BSL_Data_t *wrapped_key, BSL_Data_t cek, const char *content_key_id, size_t aes_variant)
int	BSL_Cipher_Init (BSL_Cipher_t *cipher_ctx, BSL_CipherMode_e enc, BSL_CryptoCipherAESVariant_e aes_var, const void *init_vec, int iv_len, BSL_Data_t content_enc_key)
	Initialize crypto context resources and set as encoding or decoding.
int	BSLB_Crypto_GetRegistryKey (const char *keyid, const uint8_t **secret, size_t *secret_len)
	Get pointers to an existing key, if present.
int	BSL_Cipher_AddAAD (BSL_Cipher_t *cipher_ctx, const void *aad, int aad_len)
	Add additional authenticated data (AAD) to cipher context.
int	BSL_Cipher_AddData (BSL_Cipher_t *cipher_ctx, BSL_Data_t plaintext, BSL_Data_t ciphertext)
int	BSL_Cipher_AddSeq (BSL_Cipher_t *cipher_ctx, BSL_SeqReader_t *reader, BSL_SeqWriter_t *writer)
	Add data to encrypt or decrypt to the context sequentially.
int	BSL_Cipher_GetTag (BSL_Cipher_t *cipher_ctx, void **tag)
	Get the tag of the crypto operation.
int	BSL_Cipher_SetTag (BSL_Cipher_t *cipher_ctx, const void *tag)
	Set the tag of the crypto operation.
int	BSL_Cipher_FinalizeSeq (BSL_Cipher_t *cipher_ctx, BSL_SeqWriter_t *writer)
	Finalize crypto operation.
int	BSL_Cipher_FinalizeData (BSL_Cipher_t *cipher_ctx, BSL_Data_t *extra)
int	BSL_Cipher_Deinit (BSL_Cipher_t *cipher_ctx)
	De-initialize crypto context resources.
int	BSL_Crypto_GenKey (uint8_t *key_buffer, size_t key_length)
int	BSL_Crypto_GenIV (void *buf, int size)
	Generate initialization vector (IV) for AES-GCM for BCBs.
int	BSL_Crypto_AddRegistryKey (const char *keyid, const uint8_t *secret, size_t secret_len)
	Add a new key to the crypto key registry.

Detailed Description

Abstract interface for crypto processing.

HMAC Operations:

To generate HMAC over a string,

1. Initialize the HMAC generation context: BSL_AuthCtx_Init()
2. Add data to the HMAC context. This can be done with a flat buffer: BSL_AuthCtx_DigestBuffer(), or with a sequential reader: BSL_AuthCtx_DigestSeq()
3. Finalize the HMAC context to get final tag: BSL_AuthCtx_Finalize()
4. Deinitialize the HMAC context: BSL_AuthCtx_Deinit()

Crypto Operations:

To encrypt plaintext,

1. Initialize the cipher context, using BSL_CRYPTO_ENCRYPT as the enc parameter: BSL_Cipher_Init() Also provide the initialization vector (IV), IV Length, and key ID
2. (Optional) add additional authentication data (aad) with BSL_Cipher_AddAAD()
3. Add data to the cipher context by calling BSL_Cipher_AddSeq()
4. Finalize cipher operation: calling BSL_Cipher_FinalizeSeq()
5. Get tag information: BSL_Cipher_GetTag()
6. Deinitialize the cipher context: BSL_Cipher_Deinit()

To decrypt ciphertext:

1. Initialize the cipher context, using BSL_CRYPTO_DECRYPT as the enc parameter: BSL_Cipher_Init() Also provide the initialization vector (IV), IV Length, and key ID
2. (Optional) add additional authentication data (aad) with BSL_Cipher_AddAAD()
3. Add data to the cipher context by calling BSL_Cipher_AddSeq()
4. Set tag information to be used to validate decryption: BSL_Cipher_SetTag()
5. Finalize cipher operation: calling BSL_Cipher_FinalizeSeq()

6. Deinitialize the cipher context: BSL_Cipher_Deinit()

   Todo:

   Significant perform tidying and housekeeping.

Typedef Documentation

BSL_Crypto_RandBytesFn

typedef int(* BSL_Crypto_RandBytesFn) (unsigned char *buf, int len)

Function pointer def for random bytestring generator.

Parameters

buf	buffer to fill with random bytes
len	size of random buffer

Returns

1 if success, 0 if failure

Enumeration Type Documentation

BSL_CipherMode_e

enum BSL_CipherMode_e

Enum def to define cipher contexts as encryption or decryption operations.

Enumerator
BSL_CRYPTO_ENCRYPT	We use undefined for zero, in case this value is never explicitly set and is just zero by default.

Function Documentation

BSL_AuthCtx_Deinit()

int BSL_AuthCtx_Deinit

(

BSL_AuthCtx_t *

hmac_ctx

)

Deinitialize HMAC context resources.

Parameters

[in,out]

hmac_ctx

pointer to hmac context struct to add data to

Returns

0 if successful

References BSL_AuthCtx_t::libhandle.

Referenced by BSLX_BIB_GenHMAC().

BSL_AuthCtx_DigestBuffer()

BSL_REQUIRE_CHECK int BSL_AuthCtx_DigestBuffer	(	BSL_AuthCtx_t *	hmac_ctx,
		const void *	data,
		size_t	data_len
	)

Input data to HMAC sign to context.

Parameters

[in,out]	hmac_ctx	pointer to hmac context struct to add data to
[in]	data	buffer containing data to sign
	data_len	length of incoming data buffer

Returns

0 if successful

References BSL_AuthCtx_t::libhandle.

Referenced by BSLX_BIB_GenHMAC().

BSL_AuthCtx_DigestSeq()

int BSL_AuthCtx_DigestSeq	(	BSL_AuthCtx_t *	hmac_ctx,
		BSL_SeqReader_t *	reader
	)

Input data to HMAC sign to context.

Parameters

[in,out]	hmac_ctx	pointer to hmac context struct to add data to
[in]	reader	sequential reader over data to sign

Returns

0 if successful

References BSL_AuthCtx_t::block_size, BSL_SeqReader_Get(), and BSL_AuthCtx_t::libhandle.

BSL_AuthCtx_Finalize()

int BSL_AuthCtx_Finalize	(	BSL_AuthCtx_t *	hmac_ctx,
		void **	hmac,
		size_t *	hmac_len
	)

Finalize HMAC tag.

Parameters

[in,out]	hmac_ctx	pointer to hmac context struct to add data to
[out]	hmac	ptr to hmac tag
[out]	hmac_len	ptr to tag length

Returns

0 if successful

References BSL_AuthCtx_t::libhandle.

Referenced by BSLX_BIB_GenHMAC().

BSL_AuthCtx_Init()

BSL_REQUIRE_CHECK int BSL_AuthCtx_Init	(	BSL_AuthCtx_t *	hmac_ctx,
		const char *	keyid,
		BSL_CryptoCipherSHAVariant_e	sha_var
	)

Initialize HMAC context resources and set private key and SHA variant.

Parameters

[in,out]	hmac_ctx	pointer to hmac context struct to init and set
	keyid	ID of private key to use
[in]	sha_var	SHA variant, see RFC9173 [4]

Returns

0 if successful

References BSL_AuthCtx_t::block_size, BSL_ERR_FAILURE, BSL_ERR_NOT_FOUND, BSL_LOG_ERR, BSL_AuthCtx_t::libhandle, BSLB_CryptoKey_t::pkey, BSL_AuthCtx_t::SHA_variant, and StaticKeyRegistry.

Referenced by BSLX_BIB_GenHMAC().

BSL_Cipher_AddAAD()

int BSL_Cipher_AddAAD	(	BSL_Cipher_t *	cipher_ctx,
		const void *	aad,
		int	aad_len
	)

Add additional authenticated data (AAD) to cipher context.

Parameters

cipher_ctx	pointer to context to add AAD to
aad	pointer to AAD
aad_len	length of AAD

Returns

0 if successful

References BSL_Cipher_t::libhandle.

BSL_Cipher_AddData()

int BSL_Cipher_AddData	(	BSL_Cipher_t *	cipher_ctx,
		BSL_Data_t	plaintext,
		BSL_Data_t	ciphertext
	)

Todo:

Doxygen

References BSL_Data_t::len, BSL_Cipher_t::libhandle, and BSL_Data_t::ptr.

BSL_Cipher_AddSeq()

int BSL_Cipher_AddSeq	(	BSL_Cipher_t *	cipher_ctx,
		BSL_SeqReader_t *	reader,
		BSL_SeqWriter_t *	writer
	)

Add data to encrypt or decrypt to the context sequentially.

Parameters

	cipher_ctx	pointer to context to add data to
[in]	reader	pointer to sequential reader - input to crypto operation is
[in,out]	writer	pointer to sequential writer - output of crypto operation will be writer

Returns

0 if successful

References BSL_Cipher_t::block_size, BSL_SeqReader_Get(), BSL_SeqWriter_Put(), and BSL_Cipher_t::libhandle.

BSL_Cipher_Deinit()

int BSL_Cipher_Deinit

(

BSL_Cipher_t *

cipher_ctx

)

De-initialize crypto context resources.

Parameters

cipher_ctx

pointer to context to deinitialize

Returns

0 if successful

References BSL_SUCCESS, and BSL_Cipher_t::libhandle.

BSL_Cipher_FinalizeSeq()

int BSL_Cipher_FinalizeSeq	(	BSL_Cipher_t *	cipher_ctx,
		BSL_SeqWriter_t *	writer
	)

Finalize crypto operation.

Finalize may or may not add data to writer depending on implementation.

Parameters

	cipher_ctx	pointer to context to finalize
[out]	writer	additional written data

Returns

0 if successful

References BSL_SeqWriter_Put(), and BSL_Cipher_t::libhandle.

BSL_Cipher_GetTag()

int BSL_Cipher_GetTag	(	BSL_Cipher_t *	cipher_ctx,
		void **	tag
	)

Get the tag of the crypto operation.

Parameters

	cipher_ctx	pointer to context to get tag from
[out]	tag	will contain tag information upon successful function completion

Returns

0 if successful

References BSL_Cipher_t::libhandle.

BSL_Cipher_Init()

int BSL_Cipher_Init	(	BSL_Cipher_t *	cipher_ctx,
		BSL_CipherMode_e	enc,
		BSL_CryptoCipherAESVariant_e	aes_var,
		const void *	init_vec,
		int	iv_len,
		BSL_Data_t	content_enc_key
	)

Initialize crypto context resources and set as encoding or decoding.

Parameters

cipher_ctx	pointer to context to initialize
aes_var	AES GCM variant to use
enc	enum for BSL_CRYPTO_ENCRYPT or BSL_CRYPTO_DECRYPT
init_vec	pointer to initialization vector (IV) data
iv_len	length of IV data
content_enc_key	AES key to use as Content Encryption Key.

Returns

0 if successful

References BSL_Cipher_t::AES_variant, BSL_Cipher_t::block_size, BSL_CRYPTO_ENCRYPT, BSL_ERR_FAILURE, BSL_LOG_ERR, BSL_Cipher_t::enc, BSL_Data_t::len, BSL_Cipher_t::libhandle, and BSL_Data_t::ptr.

BSL_Cipher_SetTag()

int BSL_Cipher_SetTag	(	BSL_Cipher_t *	cipher_ctx,
		const void *	tag
	)

Set the tag of the crypto operation.

Tag length is always 16 bytes

Parameters

	cipher_ctx	pointer to context to set tag of
[in]	tag	pointer to tag

Returns

0 if successful

References BSL_LOG_INFO, and BSL_Cipher_t::libhandle.

BSL_Crypto_AddRegistryKey()

int BSL_Crypto_AddRegistryKey	(	const char *	keyid,
		const uint8_t *	secret,
		size_t	secret_len
	)

Add a new key to the crypto key registry.

Parameters

keyid	key ID that crypto functions will use to access key
secret	raw key data
secret_len	length of raw key

Returns

Zero upon success.

References BSL_Data_CopyFrom(), BSL_Data_Init(), BSL_LOG_ERR, BSLB_CryptoKey_t::pkey, BSLB_CryptoKey_t::raw, and StaticKeyRegistry.

BSL_Crypto_GenIV()

int BSL_Crypto_GenIV	(	void *	buf,
		int	size
	)

Generate initialization vector (IV) for AES-GCM for BCBs.

Parameters

[in,out]	buf	to write iv to
	size	size in bytes of iv (MUST be between 8-16, SHOULD be 12 [4])

Returns

0 if successful

References rand_bytes_generator.

BSL_Crypto_SetRngGenerator()

void BSL_Crypto_SetRngGenerator

(

BSL_Crypto_RandBytesFn

rand_gen_fn

)

Set RNG generator to be used by crypto library.

Parameters

[in]

rand_gen_fn

random bytes generation function.

Warning

Intended to be used only for testing. Providing an alternative RNG may break FIPS-140 compatibility

References rand_bytes_generator.

Referenced by test_RFC9173_AppendixA_Example1_BIB_Source(), and test_RFC9173_AppendixA_Example2_BCB_Source().

BSL_Crypto_UnwrapKey()

int BSL_Crypto_UnwrapKey	(	BSL_Data_t *	unwrapped_key_output,
		BSL_Data_t	wrapped_key_plaintext,
		const char *	key_id,
		size_t	aes_variant
	)

Todo:

Doxygen

References BSL_ERR_SECURITY_CONTEXT_CRYPTO_FAILED, BSL_LOG_ERR, BSL_SUCCESS, BSLB_Crypto_GetRegistryKey(), BSL_Data_t::len, and BSL_Data_t::ptr.

BSL_Crypto_WrapKey()

int BSL_Crypto_WrapKey	(	BSL_Data_t *	wrapped_key,
		BSL_Data_t	cek,
		const char *	content_key_id,
		size_t	aes_variant
	)

Todo:

Doxygen

References BSL_LOG_ERR, BSLB_Crypto_GetRegistryKey(), BSL_Data_t::len, and BSL_Data_t::ptr.

BSL_CryptoDeinit()

void BSL_CryptoDeinit

(

void

)

Deinitialize the crypto subsystem.

This should be called at the end of the process.

References StaticKeyRegistry.

BSL_CryptoInit()

void BSL_CryptoInit

(

void

)

Initialize the crypto subsystem.

This must be called once per process.

References rand_bytes_generator, and StaticKeyRegistry.

BSLB_Crypto_GetRegistryKey()

int BSLB_Crypto_GetRegistryKey	(	const char *	keyid,
		const uint8_t **	secret,
		size_t *	secret_len
	)

Get pointers to an existing key, if present.

Parameters

	keyid	The key to search for.
[out]	secret	Pointer to the stored secret buffer, if successful.
[out]	secret_len	Pointer to the stored secret length, if successful.

Returns

Zero upon success.

References BSL_ERR_NOT_FOUND, BSL_SUCCESS, BSL_Data_t::len, BSL_Data_t::ptr, BSLB_CryptoKey_t::raw, and StaticKeyRegistry.

Referenced by BSL_Crypto_UnwrapKey(), and BSL_Crypto_WrapKey().