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_Crypto_KeyStats_t
	Structure containing statistics for individual keys. More...

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_192 , BSL_CRYPTO_AES_256 }

enum	BSL_Crypto_KeyStatCounterIndex_e { BSL_CRYPTO_KEYSTATS_TIMES_USED = 0 , BSL_CRYPTO_KEYSTATS_BYTES_PROCESSED , BSL_CRYPTO_KEYSTATS_MAX_INDEX }

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, void keyhandle, 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_ClearGeneratedKeyHandle (void *keyhandle)
	Deinit and free generated key handle.

int	BSL_Crypto_WrapKey (void kek_handle, void cek_handle, BSL_Data_t wrapped_key, void *wrapped_key_handle)
	Perform key wrap KEK and CEK sizes must match.

int	BSL_Crypto_UnwrapKey (void kek_handle, BSL_Data_t wrapped_key, void **cek_handle)
	Perform key unwrap CEK size expected to match size of KEK.

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, void *key_handle)
	Initialize crypto context resources and set as encoding or decoding.

int	BSL_Crypto_GetRegistryKey (const char keyid, void *key_handle)
	Get pointers to an existing key, if present.

int	BSL_Crypto_RemoveRegistryKey (const char *keyid)
	Erase key entry from crypto library registry, 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 (size_t key_length, void **key_out)
	Generate a new cryptographic key.

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.

int	BSL_Crypto_GetKeyStatistics (const char keyid, BSL_Crypto_KeyStats_t stats)
	Retrieve statistics related to a crypto key.

Detailed Description

Abstract interface for crypto processing.

HMAC Operations:

To generate HMAC over a string,

Initialize the HMAC generation context: BSL_AuthCtx_Init()
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()
Finalize the HMAC context to get final tag: BSL_AuthCtx_Finalize()
Deinitialize the HMAC context: BSL_AuthCtx_Deinit()

Crypto Operations:

To encrypt plaintext,

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
(Optional) add additional authentication data (aad) with BSL_Cipher_AddAAD()
Add data to the cipher context by calling BSL_Cipher_AddSeq()
Finalize cipher operation: calling BSL_Cipher_FinalizeSeq()
Get tag information: BSL_Cipher_GetTag()
Deinitialize the cipher context: BSL_Cipher_Deinit()

To decrypt ciphertext:

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
(Optional) add additional authentication data (aad) with BSL_Cipher_AddAAD()
Add data to the cipher context by calling BSL_Cipher_AddSeq()
Set tag information to be used to validate decryption: BSL_Cipher_SetTag()
Finalize cipher operation: calling BSL_Cipher_FinalizeSeq()
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::keyhandle, BSL_AuthCtx_t::libhandle, and BSL_CryptoKey_t::stats.

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(), BSL_AuthCtx_t::keyhandle, BSL_AuthCtx_t::libhandle, and BSL_CryptoKey_t::stats.

◆ 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,
		void *	keyhandle,
		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
[in]	keyhandle	handle for 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_LOG_ERR, BSL_AuthCtx_t::keyhandle, BSL_AuthCtx_t::libhandle, BSL_CryptoKey_t::pkey, BSL_AuthCtx_t::SHA_variant, and BSL_CryptoKey_t::stats.

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::keyhandle, BSL_Cipher_t::libhandle, and BSL_CryptoKey_t::stats.

Referenced by BSLX_BCB_Encrypt().

◆ BSL_Cipher_AddData()

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

Todo:: Doxygen

References BSL_Cipher_t::keyhandle, BSL_Data_t::len, BSL_Cipher_t::libhandle, BSL_Data_t::ptr, and BSL_CryptoKey_t::stats.

◆ 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
[in]	writer	pointer to sequential writer - output of crypto operation

Returns: 0 if successful

References BSL_Cipher_t::block_size, BSL_LOG_DEBUG, BSL_SeqReader_Get(), BSL_SeqWriter_Put(), BSL_Cipher_t::keyhandle, BSL_Cipher_t::libhandle, and BSL_CryptoKey_t::stats.

Referenced by BSLX_BCB_Encrypt().

◆ 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.

Referenced by BSLX_BCB_Encrypt().

◆ 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_Cipher_t::block_size, BSL_ERR_FAILURE, BSL_LOG_ERR, BSL_SeqWriter_Put(), and BSL_Cipher_t::libhandle.

Referenced by BSLX_BCB_Encrypt().

◆ 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.

Referenced by BSLX_BCB_Encrypt().

◆ 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,
		void *	key_handle
	)

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
key_handle	key handle to use

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_Cipher_t::keyhandle, BSL_Cipher_t::libhandle, BSL_Data_t::ptr, BSL_CryptoKey_t::raw, and BSL_CryptoKey_t::stats.

Referenced by BSLX_BCB_Encrypt().

◆ 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, BSL_CryptoKey_t::pkey, BSL_CryptoKey_t::raw, and StaticKeyRegistry.

◆ BSL_Crypto_ClearGeneratedKeyHandle()

int BSL_Crypto_ClearGeneratedKeyHandle ( void * keyhandle )

Deinit and free generated key handle.

Parameters

[in] keyhandle key handle to clear. Key handle assumed to be generated, not present in key registry, and allocated with BSL_MALLOC().

Returns: 0 if successfully cleared key handle

References BSL_FREE, and BSL_SUCCESS.

Referenced by BSLX_BCB_Encrypt(), and BSLX_BIB_GenHMAC().

◆ 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.

Referenced by BSLX_BCB_Encrypt().

◆ BSL_Crypto_GenKey()

int BSL_Crypto_GenKey	(	size_t	key_length,
		void **	key_out
	)

Generate a new cryptographic key.

Parameters

[in]	key_length	length of new key. Should be 16 or 32
[in,out]	key_out	pointer to pointer for new key handle, allocated with BSL_MALLOC()

References BSL_Data_InitBuffer(), BSL_MALLOC, BSL_SUCCESS, BSL_Data_t::len, BSL_CryptoKey_t::pkey, BSL_Data_t::ptr, rand_bytes_generator, and BSL_CryptoKey_t::raw.

Referenced by BSLX_BCB_Encrypt(), and BSLX_BIB_GenHMAC().

◆ BSL_Crypto_GetKeyStatistics()

int BSL_Crypto_GetKeyStatistics	(	const char *	keyid,
		BSL_Crypto_KeyStats_t *	stats
	)

Retrieve statistics related to a crypto key.

Parameters

[in]	keyid	key ID of a key in the crypto registry to retrieve the stats of
[out]	stats	struct containing statistics related to the key id

References BSL_ERR_NOT_FOUND, BSL_SUCCESS, StaticKeyRegistry, and BSL_CryptoKey_t::stats.

◆ BSL_Crypto_GetRegistryKey()

int BSL_Crypto_GetRegistryKey	(	const char *	keyid,
		void **	key_handle
	)

Get pointers to an existing key, if present.

Parameters

	keyid	The key to search for.
[in,out]	key_handle	pointer to pointer for new key handle

Returns: Zero upon success.

References BSL_ERR_NOT_FOUND, BSL_SUCCESS, and StaticKeyRegistry.

Referenced by BSLX_BCB_Encrypt(), and BSLX_BIB_GenHMAC().

◆ BSL_Crypto_RemoveRegistryKey()

int BSL_Crypto_RemoveRegistryKey ( const char * keyid )

Erase key entry from crypto library registry, if present.

Parameters

[in] keyid key ID of key to remove

References BSL_SUCCESS, and StaticKeyRegistry.

◆ 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 mock_bpa_register_policy_from_json(), test_RFC9173_AppendixA_Example1_BIB_Source(), and test_RFC9173_AppendixA_Example2_BCB_Source().

◆ BSL_Crypto_UnwrapKey()

int BSL_Crypto_UnwrapKey	(	void *	kek_handle,
		BSL_Data_t *	wrapped_key,
		void **	cek_handle
	)

Perform key unwrap CEK size expected to match size of KEK.

Parameters

[in]	kek_handle	key encryption key handle (decryption key)
[in]	wrapped_key	input wrapped key (ciphertext) bytes
[in,out]	cek_handle	output content encryption key (plaintext) handle, allocated with BSL_MALLOC()

wrapped key always 8 bytes greater than CEK [7] (2.2.1)

References BSL_Data_AppendFrom(), BSL_Data_Resize(), BSL_ERR_SECURITY_CONTEXT_CRYPTO_FAILED, BSL_FREE, BSL_LOG_DEBUG, BSL_LOG_ERR, BSL_MALLOC, BSL_Data_t::len, BSL_CryptoKey_t::pkey, BSL_Data_t::ptr, BSL_CryptoKey_t::raw, and BSL_CryptoKey_t::stats.

Referenced by BSLX_BIB_GenHMAC().

◆ BSL_Crypto_WrapKey()

int BSL_Crypto_WrapKey	(	void *	kek_handle,
		void *	cek_handle,
		BSL_Data_t *	wrapped_key,
		void **	wrapped_key_handle
	)

Perform key wrap KEK and CEK sizes must match.

Parameters

[in]	kek_handle	key encryption key handle (encryption key)
[in]	cek_handle	content encryption key handle (encryption data)
[in,out]	wrapped_key	output wrapped key (ciphertext) bytes
[in,out]	wrapped_key_handle	output wrapped key (ciphertext) handle, allocated with BSL_MALLOC(). Set to NULL if handle not needed.

References BSL_Data_AppendFrom(), BSL_Data_CopyFrom(), BSL_Data_Init(), BSL_ERR_SECURITY_CONTEXT_CRYPTO_FAILED, BSL_LOG_DEBUG, BSL_LOG_ERR, BSL_MALLOC, BSL_Data_t::len, BSL_CryptoKey_t::pkey, BSL_Data_t::ptr, BSL_CryptoKey_t::raw, and BSL_CryptoKey_t::stats.

Referenced by BSLX_BCB_Encrypt(), and BSLX_BIB_GenHMAC().

◆ BSL_CryptoDeinit()

void BSL_CryptoDeinit ( void )

Deinitialize the crypto subsystem.

This should be called at the end of the process.

References StaticKeyRegistry.

Referenced by main().

◆ BSL_CryptoInit()

void BSL_CryptoInit ( void )

Initialize the crypto subsystem.

This must be called once per process.

References rand_bytes_generator, and StaticKeyRegistry.

Referenced by main().

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ BSL_Crypto_RandBytesFn

Enumeration Type Documentation

◆ BSL_CipherMode_e

Function Documentation

◆ BSL_AuthCtx_Deinit()

◆ BSL_AuthCtx_DigestBuffer()

◆ BSL_AuthCtx_DigestSeq()

◆ BSL_AuthCtx_Finalize()

◆ BSL_AuthCtx_Init()

◆ BSL_Cipher_AddAAD()

◆ BSL_Cipher_AddData()

◆ BSL_Cipher_AddSeq()

◆ BSL_Cipher_Deinit()

◆ BSL_Cipher_FinalizeSeq()

◆ BSL_Cipher_GetTag()

◆ BSL_Cipher_Init()

◆ BSL_Cipher_SetTag()

◆ BSL_Crypto_AddRegistryKey()

◆ BSL_Crypto_ClearGeneratedKeyHandle()

◆ BSL_Crypto_GenIV()

◆ BSL_Crypto_GenKey()

◆ BSL_Crypto_GetKeyStatistics()

◆ BSL_Crypto_GetRegistryKey()

◆ BSL_Crypto_RemoveRegistryKey()

◆ BSL_Crypto_SetRngGenerator()

◆ BSL_Crypto_UnwrapKey()

◆ BSL_Crypto_WrapKey()

◆ BSL_CryptoDeinit()

◆ BSL_CryptoInit()