Backend cryptography implementation. More...

#include "CryptoInterface.h"
#include "bsl/BPSecLib_Private.h"
#include "bsl/front/TextUtil.h"
#include "bsl/dynamic/IdValPair.h"
#include <m-bstring.h>
#include <m-dict.h>
#include <m-shared-ptr.h>
#include <openssl/core_names.h>
#include <openssl/err.h>
#include <openssl/evp.h>
#include <openssl/kdf.h>
#include <openssl/rand.h>

Include dependency graph for CryptoInterface.c:

Data Structures
struct	BSL_CryptoKey_t
	Struct to hold private key information. More...

Macros
#define	M_OPL_BSL_CryptoKey_t() M_OPEXTEND(M_POD_OPLIST, INIT(API_2(BSL_CryptoKey_Init)), INIT_SET(0), SET(0), CLEAR(API_2(BSL_CryptoKey_Deinit)))
	M*LIB OPLIST for BSL_CryptoKey_t.

#define	BSL_Crypto_PtrOrZero(ptr) (ptr) ? (ptr) : (void *)&BSL_Crypto_zero

Functions
static void	BSL_CryptoKey_Init (BSL_CryptoKey_t *key)

static void	BSL_CryptoKey_Deinit (BSL_CryptoKey_t *key)

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.

void	BSL_Crypto_ReleaseKeyHandle (BSL_Crypto_KeyHandle_t keyhandle)
	Release a key handle after it is done being used.

bool	BSL_Crypto_CompareKeys (BSL_Crypto_KeyHandle_t hdl1, BSL_Crypto_KeyHandle_t hdl2)
	Compare two keys in a time-invariant way.

int	BSL_Crypto_UnwrapKey (BSL_Crypto_KeyHandle_t kek_handle, const BSL_Data_t wrapped_key, BSL_Crypto_KeyHandle_t cek_handle)
	Perform key unwrap.

int	BSL_Crypto_WrapKey (BSL_Crypto_KeyHandle_t kek_handle, BSL_Crypto_KeyHandle_t cek_handle, BSL_Data_t *wrapped_key)
	Perform key wrap.

int	BSL_Crypto_KDF (BSL_Crypto_KeyHandle_t kdk_handle, BSL_Crypto_KDFVariant_t func, const BSL_Data_t salt, const BSL_Data_t info, size_t keylen, BSL_Crypto_KeyHandle_t *cek_handle)
	Perform key derivation.

int	BSL_AuthCtx_Init (BSL_AuthCtx_t *hmac_ctx, BSL_Crypto_KeyHandle_t keyhandle, BSL_Crypto_SHAVariant_e sha_var)
	Initialize HMAC context resources and set private key and SHA variant.

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, BSL_Data_t tag)
	Finalize HMAC tag.

void	BSL_AuthCtx_Deinit (BSL_AuthCtx_t *hmac_ctx)
	Deinitialize HMAC context resources.

bool	BSL_Crypto_Compare (const void data1, size_t size1, const void data2, size_t size2)
	Compare two blocks of data in a time-invariant way.

int	BSL_Cipher_Init (BSL_Cipher_t cipher_ctx, BSL_CipherMode_e enc, BSL_Crypto_AESVariant_e aes_var, const BSL_Data_t iv_val, BSL_Crypto_KeyHandle_t keyhandle)
	Initialize crypto context resources and set as encoding or decoding.

int	BSL_Cipher_AddAadBuffer (BSL_Cipher_t cipher_ctx, const void aad, size_t aad_len)
	Add additional authenticated data (AAD) to cipher context.

int	BSL_Cipher_AddAadSeq (BSL_Cipher_t cipher_ctx, BSL_SeqReader_t reader)
	Add AAD from sequential reader.

int	BSL_Cipher_AddSeq (BSL_Cipher_t cipher_ctx, BSL_SeqReader_t reader, BSL_SeqWriter_t *writer, size_t limit)
	Add data to encrypt or decrypt to the context sequentially.

size_t	BSL_Cipher_TagLen (const BSL_Cipher_t *cipher_ctx)
	Determine the size of the authentication tag.

int	BSL_Cipher_GetTag (BSL_Cipher_t cipher_ctx, BSL_Data_t tag)
	Get the tag of the crypto operation.

int	BSL_Cipher_SetTag (BSL_Cipher_t cipher_ctx, const BSL_Data_t 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_Deinit (BSL_Cipher_t *cipher_ctx)
	De-initialize crypto context resources.

int	BSL_Crypto_GenKey (size_t key_length, BSL_Crypto_KeyHandle_t *key_out)
	Generate a new cryptographic key.

int	BSL_Crypto_LoadKey (const uint8_t secret, size_t secret_len, BSL_Crypto_KeyHandle_t key_out)
	Load a new cryptographic key.

int	BSL_Crypto_GenIV (BSL_Data_t *buf)
	Generate random bytes.

int	BSL_Crypto_AddRegistryKey (const BSL_Data_t *keyid, BSL_Crypto_KeyHandle_t handle)
	Add a new key to the crypto key registry.

BSL_IdValPair_t *	BSL_Crypto_SetKeyParameter (BSL_Crypto_KeyHandle_t handle, int64_t param_id)
	Add a context-specific parameter to a known key.

const BSL_IdValPair_t *	BSL_Crypto_GetKeyParameter (BSL_Crypto_KeyHandle_t handle, int64_t param_id)
	Get key parameter for read-only access.

int	BSL_Crypto_GetRegistryKey (const BSL_Data_t keyid, BSL_Crypto_KeyHandle_t key_handle)
	Get pointers to an existing key, if present.

int	BSL_Crypto_RemoveRegistryKey (const BSL_Data_t *keyid)
	Erase key entry from crypto library registry, if present.

int	BSL_Crypto_GetKeyStatistics (BSL_Crypto_KeyHandle_t handle, BSL_Crypto_KeyStats_t *stats)
	Retrieve statistics related to a crypto key.

Variables
static BSL_Crypto_RandBytesFn	rand_bytes_generator
	Random bytes generator.

static BSL_CryptoKeyDict_t	StaticKeyRegistry
	Crypto key registry.

static pthread_mutex_t	StaticCryptoMutex = PTHREAD_MUTEX_INITIALIZER

static const uint8_t	BSL_Crypto_zero = 0

Detailed Description

Backend cryptography implementation.

Macro Definition Documentation

◆ BSL_Crypto_PtrOrZero

#define BSL_Crypto_PtrOrZero ( ptr ) (ptr) ? (ptr) : (void *)&BSL_Crypto_zero

◆ M_OPL_BSL_CryptoKey_t

#define M_OPL_BSL_CryptoKey_t ( ) M_OPEXTEND(M_POD_OPLIST, INIT(API_2(BSL_CryptoKey_Init)), INIT_SET(0), SET(0), CLEAR(API_2(BSL_CryptoKey_Deinit)))

M*LIB OPLIST for BSL_CryptoKey_t.

Function Documentation

◆ BSL_AuthCtx_Deinit()

void 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

References ASSERT_ARG_NONNULL, BSL_Data_Deinit(), BSL_AuthCtx_t::in_buf, BSL_AuthCtx_t::keyhandle, and BSL_AuthCtx_t::libhandle.

Referenced by BSLX_BIB_GenHMAC(), and BSLX_CoseSc_Deinit().

◆ BSL_AuthCtx_DigestBuffer()

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, which is internally limited to INT_MAX

Returns: 0 if successful

References ASSERT_ARG_NONNULL, BSL_CRYPTO_KEYSTATS_BYTES_PROCESSED, BSL_LOG_DEBUG, BSL_LOG_PLAINTEXT_PTR, CHK_PRECONDITION, CHK_PROPERTY, BSL_AuthCtx_t::keyhandle, BSL_AuthCtx_t::libhandle, BSL_CryptoKey_t::stats, BSL_Crypto_KeyStats_t::stats, and BSL_CryptoKey_t::stats_mutex.

Referenced by BSLX_BIB_GenHMAC(), BSLX_CoseSc_Mac_Compute(), and switch().

◆ 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 ASSERT_ARG_NONNULL, BSL_AuthCtx_t::block_size, BSL_CRYPTO_KEYSTATS_BYTES_PROCESSED, BSL_LOG_DEBUG, BSL_LOG_PLAINTEXT_PTR, BSL_SeqReader_Get(), CHK_PROPERTY, BSL_AuthCtx_t::in_buf, BSL_AuthCtx_t::keyhandle, BSL_AuthCtx_t::libhandle, BSL_Data_t::ptr, BSL_CryptoKey_t::stats, BSL_Crypto_KeyStats_t::stats, and BSL_CryptoKey_t::stats_mutex.

Referenced by BSLX_CoseSc_Mac_Compute(), and switch().

◆ BSL_AuthCtx_Finalize()

int BSL_AuthCtx_Finalize	(	BSL_AuthCtx_t *	hmac_ctx,
		BSL_Data_t *	tag
	)

Finalize HMAC tag.

Parameters

[in,out]	hmac_ctx	pointer to hmac context struct to add data to
[out]	tag	The HMAC output buffer to resize and populate.

Returns: 0 if successful

References ASSERT_ARG_NONNULL, BSL_Data_Resize(), BSL_LOG_DEBUG, BSL_LOG_PLAINTEXT_PTR, CHK_PROPERTY, BSL_Data_t::len, BSL_AuthCtx_t::libhandle, BSL_Data_t::ptr, and tag.

Referenced by BSLX_BIB_GenHMAC(), and BSLX_CoseSc_Mac_Compute().

◆ BSL_AuthCtx_Init()

int BSL_AuthCtx_Init	(	BSL_AuthCtx_t *	hmac_ctx,
		BSL_Crypto_KeyHandle_t	keyhandle,
		BSL_Crypto_SHAVariant_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. The HMAC context keeps its own reference to this handle.
[in]	sha_var	SHA variant, see RFC9173 [2]

Returns: 0 if successful

References BSL_AuthCtx_t::block_size, BSL_CRYPTO_KEYSTATS_TIMES_USED, BSL_CRYPTO_SHA_256, BSL_CRYPTO_SHA_384, BSL_CRYPTO_SHA_512, BSL_Data_InitBuffer(), BSL_ERR_SECURITY_CONTEXT_CRYPTO_FAILED, BSL_LOG_ERR, BSL_LOG_PLAINTEXT_PTR, CHK_ARG_NONNULL, CHK_PRECONDITION, CHK_PROPERTY, BSL_AuthCtx_t::in_buf, BSL_AuthCtx_t::keyhandle, keyhandle, BSL_Data_t::len, BSL_AuthCtx_t::libhandle, BSL_Data_t::ptr, BSL_CryptoKey_t::raw, sha_var, BSL_CryptoKey_t::stats, BSL_Crypto_KeyStats_t::stats, and BSL_CryptoKey_t::stats_mutex.

Referenced by BSLX_BIB_GenHMAC(), and BSLX_CoseSc_Mac_Compute().

◆ BSL_Cipher_AddAadBuffer()

int BSL_Cipher_AddAadBuffer	(	BSL_Cipher_t *	cipher_ctx,
		const void *	aad,
		size_t	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, which is internally limited to INT_MAX.

Returns: 0 if successful

References ASSERT_ARG_NONNULL, BSL_CRYPTO_KEYSTATS_BYTES_PROCESSED, BSL_LOG_DEBUG, BSL_LOG_PLAINTEXT_PTR, CHK_PRECONDITION, CHK_PROPERTY, BSL_Cipher_t::keyhandle, BSL_Cipher_t::libhandle, BSL_CryptoKey_t::stats, BSL_Crypto_KeyStats_t::stats, and BSL_CryptoKey_t::stats_mutex.

Referenced by BSLX_BCB_Decrypt(), BSLX_BCB_Encrypt(), BSLX_CoseSc_Encrypt_Compute(), test_decrypt(), and test_encrypt().

◆ BSL_Cipher_AddAadSeq()

int BSL_Cipher_AddAadSeq	(	BSL_Cipher_t *	cipher_ctx,
		BSL_SeqReader_t *	reader
	)

Add AAD from sequential reader.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

References ASSERT_ARG_NONNULL, BSL_Cipher_t::block_size, BSL_CRYPTO_KEYSTATS_BYTES_PROCESSED, BSL_LOG_PLAINTEXT_PTR, BSL_SeqReader_Get(), CHK_PROPERTY, BSL_Cipher_t::in_buf, BSL_Cipher_t::keyhandle, BSL_Cipher_t::libhandle, BSL_Data_t::ptr, BSL_CryptoKey_t::stats, BSL_Crypto_KeyStats_t::stats, and BSL_CryptoKey_t::stats_mutex.

Referenced by BSLX_CoseSc_Encrypt_Compute().

◆ BSL_Cipher_AddSeq()

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

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), or NULL (crypto output will not be written)
	limit	The number of bytes of the reader to read and process. This can be shorter than the full length if the ciphertext contains an authentication tag.

Returns: 0 if successful

References ASSERT_ARG_NONNULL, BSL_Cipher_t::block_size, BSL_CRYPTO_KEYSTATS_BYTES_PROCESSED, BSL_LOG_DEBUG, BSL_LOG_PLAINTEXT_PTR, BSL_SeqReader_Get(), BSL_SeqWriter_Put(), BSL_SUCCESS, CHK_PROPERTY, BSL_Cipher_t::in_buf, BSL_Cipher_t::keyhandle, BSL_Cipher_t::libhandle, BSL_Cipher_t::out_buf, BSL_Data_t::ptr, BSL_CryptoKey_t::stats, BSL_Crypto_KeyStats_t::stats, and BSL_CryptoKey_t::stats_mutex.

Referenced by BSLX_BCB_Decrypt(), BSLX_BCB_Encrypt(), BSLX_CoseSc_Encrypt_Compute(), test_decrypt(), and test_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_Data_Deinit(), BSL_SUCCESS, CHK_ARG_NONNULL, BSL_Cipher_t::in_buf, BSL_Cipher_t::keyhandle, BSL_Cipher_t::libhandle, and BSL_Cipher_t::out_buf.

Referenced by BSLX_BCB_Decrypt(), BSLX_BCB_Encrypt(), BSLX_CoseSc_Deinit(), test_decrypt(), and test_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_DEBUG, BSL_LOG_ERR, BSL_SeqWriter_Put(), BSL_SUCCESS, CHK_ARG_NONNULL, BSL_Cipher_t::libhandle, BSL_Cipher_t::out_buf, and BSL_Data_t::ptr.

Referenced by BSLX_BCB_Decrypt(), BSLX_BCB_Encrypt(), BSLX_CoseSc_Encrypt_Compute(), test_decrypt(), and test_encrypt().

◆ BSL_Cipher_GetTag()

int BSL_Cipher_GetTag	(	BSL_Cipher_t *	cipher_ctx,
		BSL_Data_t *	tag
	)

Get the tag of the crypto operation.

Parameters

	cipher_ctx	pointer to context to get tag from
[out]	tag	will be resized and contain data upon successful function completion

Returns: 0 if successful

References ASSERT_ARG_NONNULL, BSL_Data_Resize(), BSL_LOG_DEBUG, BSL_LOG_PLAINTEXT_PTR, CHK_PROPERTY, BSL_Data_t::len, BSL_Cipher_t::libhandle, BSL_Data_t::ptr, and tag.

Referenced by BSLX_BCB_Encrypt(), BSLX_CoseSc_Encrypt_Compute(), and test_encrypt().

◆ BSL_Cipher_Init()

int BSL_Cipher_Init	(	BSL_Cipher_t *	cipher_ctx,
		BSL_CipherMode_e	enc,
		BSL_Crypto_AESVariant_e	aes_var,
		const BSL_Data_t *	iv_val,
		BSL_Crypto_KeyHandle_t	key_handle
	)

Initialize crypto context resources and set as encoding or decoding.

Parameters

[out]	cipher_ctx	pointer to context to initialize
	aes_var	AES GCM variant to use
	enc	enum for BSL_CRYPTO_ENCRYPT or BSL_CRYPTO_DECRYPT
[in]	iv_val	The initialization vector (IV) data, which must be non-empty. The length is internally limited to INT_MAX
[in]	key_handle	key handle to use. The cipher context keeps its own reference to this handle.

Returns: 0 if successful

References BSL_Cipher_t::AES_variant, ASSERT_ARG_NONNULL, BSL_Cipher_t::block_size, BSL_CRYPTO_AES_128, BSL_CRYPTO_AES_192, BSL_CRYPTO_AES_256, BSL_CRYPTO_ENCRYPT, BSL_CRYPTO_KEYSTATS_TIMES_USED, BSL_Data_InitBuffer(), BSL_ERR_FAILURE, BSL_LOG_ERR, BSL_LOG_PLAINTEXT_PTR, CHK_PRECONDITION, CHK_PROPERTY, BSL_Cipher_t::enc, BSL_Cipher_t::in_buf, BSL_Cipher_t::keyhandle, keyhandle, BSL_Data_t::len, BSL_Cipher_t::libhandle, BSL_Cipher_t::out_buf, BSL_Data_t::ptr, BSL_CryptoKey_t::raw, BSL_CryptoKey_t::stats, BSL_Crypto_KeyStats_t::stats, and BSL_CryptoKey_t::stats_mutex.

Referenced by BSLX_BCB_Decrypt(), BSLX_BCB_Encrypt(), BSLX_CoseSc_Encrypt_Compute(), test_decrypt(), and test_encrypt().

◆ BSL_Cipher_SetTag()

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

Set the tag of the crypto operation.

Parameters

	cipher_ctx	pointer to context to set tag of
[in]	tag	pointer to tag to read from.

Returns: 0 if successful

References ASSERT_ARG_NONNULL, BSL_LOG_DEBUG, BSL_LOG_PLAINTEXT_PTR, CHK_PROPERTY, BSL_Data_t::len, BSL_Cipher_t::libhandle, BSL_Data_t::ptr, and tag.

Referenced by BSLX_BCB_Decrypt(), BSLX_CoseSc_Encrypt_Compute(), and test_decrypt().

◆ BSL_Cipher_TagLen()

size_t BSL_Cipher_TagLen ( const BSL_Cipher_t * cipher_ctx )

Determine the size of the authentication tag.

This will be the output of BSL_Cipher_GetTag() and the input of BSL_Cipher_SetTag().

Returns: The non-zero tag length for a valid cipher state.

References ASSERT_ARG_NONNULL, and BSL_Cipher_t::libhandle.

Referenced by BSLX_CoseSc_Encrypt_Compute().

◆ BSL_Crypto_AddRegistryKey()

int BSL_Crypto_AddRegistryKey	(	const BSL_Data_t *	keyid,
		BSL_Crypto_KeyHandle_t	handle
	)

Add a new key to the crypto key registry.

Parameters

[in]	keyid	key ID that crypto functions will use to access key
[out]	handle	Key handle to add to the registry. Once the key is added it should be treated as read-only for thread-safety purposes. When handle is output, the handle must be released with BSL_Crypto_ReleaseKeyHandle() when it is done being used.

Returns: Zero upon success.

References ASSERT_ARG_NONNULL, CHK_ARG_NONNULL, keyid, StaticCryptoMutex, and StaticKeyRegistry.

Referenced by BSL_Crypto_AddRegistryKeyName(), mock_bpa_key_registry_cosekey_decode(), mock_bpa_key_registry_init_jwk(), test_AppendixA_Example1_BIB_Source(), test_AppendixA_Example1_BIB_VerifyAccept(), test_AppendixA_Example4_BCB_Source(), test_AppendixA_Example4_BCB_VerifyAccept(), test_AppendixA_Example5_BCB_Source(), test_AppendixA_Example5_BCB_VerifyAccept(), test_AppendixA_Example6_BCB_Source(), test_CCSDS_Example_Mac_Source(), test_CCSDS_Example_Mac_VerifyAccept(), and test_key_stats().

◆ BSL_Crypto_Compare()

bool BSL_Crypto_Compare	(	const void *	data1,
		size_t	size1,
		const void *	data2,
		size_t	size2
	)

Compare two blocks of data in a time-invariant way.

This avoids side channel attacks which depend on comparison time.

Parameters

[in]	data1	The first pointer.
	size1	The size of `data1` block.
[in]	data2	The second pointer.
	size2	The size of `data2` block.

Returns: True if they compare equal.

Referenced by BSL_Crypto_CompareKeys(), BSLX_BIB_Execute(), BSLX_CoseSc_Mac0_VerifyAccept(), and BSLX_CoseSc_Mac_VerifyAccept().

◆ BSL_Crypto_CompareKeys()

bool BSL_Crypto_CompareKeys	(	BSL_Crypto_KeyHandle_t	hdl1,
		BSL_Crypto_KeyHandle_t	hdl2
	)

Compare two keys in a time-invariant way.

This avoids side channel attacks which depend on comparison time.

Parameters

[in]	hdl1	The first key handle.
[in]	hdl2	The second key handle.

Returns: True if they compare equal.

References BSL_Crypto_Compare(), BSL_Data_t::len, BSL_Data_t::ptr, and BSL_CryptoKey_t::raw.

Referenced by TEST_CASE().

◆ BSL_Crypto_GenIV()

int BSL_Crypto_GenIV ( BSL_Data_t * buf )

Generate random bytes.

This can be used for cipher initialization vector (IV) or KDF salt.

Parameters

[in,out] buf to write data into without changing its size. The size in bytes needed is determined by the calling context.

Returns: 0 if successful

References BSL_SUCCESS, CHK_ARG_NONNULL, CHK_PROPERTY, BSL_Data_t::len, BSL_Data_t::ptr, and rand_bytes_generator.

Referenced by BSLX_BCB_Encrypt(), BSLX_CoseSc_GenerateNonce(), test_crypto_generate_iv(), test_decrypt(), and test_encrypt().

◆ BSL_Crypto_GenKey()

int BSL_Crypto_GenKey	(	size_t	key_length,
		BSL_Crypto_KeyHandle_t *	key_out
	)

Generate a new cryptographic key.

Parameters

[in]	key_length	length of new key in bytes.
[out]	key_out	pointer to pointer for new key handle. The handle must be released with BSL_Crypto_ReleaseKeyHandle() when it is done being used.

References BSL_Data_Resize(), BSL_ERR_FAILURE, BSL_SUCCESS, CHK_ARG_EXPR, CHK_ARG_NONNULL, CHK_PROPERTY, BSL_Data_t::len, BSL_Data_t::ptr, rand_bytes_generator, and BSL_CryptoKey_t::raw.

Referenced by BSLX_BCB_Encrypt(), BSLX_BIB_GenHMAC(), and BSLX_CoseSc_GenerateContentKey().

◆ BSL_Crypto_GetKeyParameter()

const BSL_IdValPair_t * BSL_Crypto_GetKeyParameter	(	BSL_Crypto_KeyHandle_t	handle,
		int64_t	param_id
	)

Get key parameter for read-only access.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

References ASSERT_ARG_NONNULL, and BSL_CryptoKey_t::params.

Referenced by BSLX_CoseSc_ExtractIV(), BSLX_CoseSc_GenerateIV(), and BSLX_CoseSc_GetAndValidateKey().

◆ BSL_Crypto_GetKeyStatistics()

int BSL_Crypto_GetKeyStatistics	(	BSL_Crypto_KeyHandle_t	handle,
		BSL_Crypto_KeyStats_t *	stats
	)

Retrieve statistics related to a crypto key.

Parameters

[in]	handle	The handle of a key in the crypto registry to retrieve the stats of.
[out]	stats	struct containing statistics related to the key id

References ASSERT_ARG_NONNULL, BSL_SUCCESS, CHK_ARG_NONNULL, BSL_CryptoKey_t::stats, and BSL_CryptoKey_t::stats_mutex.

Referenced by BSLX_CoseSc_GenerateNonce(), test_AppendixA_Example1_BIB_Source(), test_AppendixA_Example1_BIB_VerifyAccept(), test_AppendixA_Example4_BCB_Source(), test_AppendixA_Example4_BCB_VerifyAccept(), test_AppendixA_Example5_BCB_Source(), test_AppendixA_Example5_BCB_VerifyAccept(), test_AppendixA_Example6_BCB_Source(), TEST_CASE(), TEST_CASE(), test_CCSDS_Example_Mac_Source(), test_CCSDS_Example_Mac_VerifyAccept(), and test_key_stats().

◆ BSL_Crypto_GetRegistryKey()

int BSL_Crypto_GetRegistryKey	(	const BSL_Data_t *	keyid,
		BSL_Crypto_KeyHandle_t *	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. The handle must be released with BSL_Crypto_ReleaseKeyHandle() when it is done being used.

Returns: Zero if the key was present.

References ASSERT_ARG_NONNULL, BSL_ERR_NOT_FOUND, BSL_SUCCESS, CHK_ARG_NONNULL, keyid, StaticCryptoMutex, and StaticKeyRegistry.

Referenced by BSL_Crypto_GetRegistryKeyName(), BSLX_BCB_Decrypt(), BSLX_BCB_Encrypt(), BSLX_BIB_GenHMAC(), and BSLX_CoseSc_GetAndValidateKey().

◆ BSL_Crypto_KDF()

int BSL_Crypto_KDF	(	BSL_Crypto_KeyHandle_t	kdk_handle,
		BSL_Crypto_KDFVariant_t	func,
		const BSL_Data_t *	salt,
		const BSL_Data_t *	info,
		size_t	keylen,
		BSL_Crypto_KeyHandle_t *	cek_handle
	)

Perform key derivation.

Parameters

[in]	kdk_handle	The derivation key handle.
	func	The derivation function variation.
[in]	salt	The extract step salt.
[in]	info	The expand step context data.
	keylen	The expand step length.
[in,out]	cek_handle	output content encryption key handle.

References BSL_CRYPTO_KDF_HKDF_SHA_256, BSL_CRYPTO_KDF_HKDF_SHA_512, BSL_CRYPTO_KEYSTATS_BYTES_PROCESSED, BSL_CRYPTO_KEYSTATS_TIMES_USED, BSL_Crypto_PtrOrZero, BSL_Data_Resize(), BSL_ERR_SECURITY_CONTEXT_CRYPTO_FAILED, BSL_LOG_DEBUG, BSL_LOG_ERR, BSL_LOG_PLAINTEXT_PTR, BSL_SUCCESS, CHK_ARG_NONNULL, CHK_PRECONDITION, CHK_PROPERTY, BSL_Data_t::len, BSL_Data_t::ptr, BSL_CryptoKey_t::raw, BSL_CryptoKey_t::stats, BSL_Crypto_KeyStats_t::stats, and BSL_CryptoKey_t::stats_mutex.

Referenced by BSLX_CoseSc_HkdfContentKey(), and TEST_CASE().

◆ BSL_Crypto_LoadKey()

int BSL_Crypto_LoadKey	(	const uint8_t *	secret,
		size_t	secret_len,
		BSL_Crypto_KeyHandle_t *	key_out
	)

Load a new cryptographic key.

Parameters

[in]	secret	raw symmetric key.
	secret_len	length of `secret` data.
[out]	key_out	pointer to pointer for new key handle. The handle must be released with BSL_Crypto_ReleaseKeyHandle() when it is done being used.

References BSL_Data_CopyFrom(), BSL_LOG_ERR, BSL_SUCCESS, CHK_ARG_EXPR, CHK_ARG_NONNULL, CHK_PROPERTY, and BSL_CryptoKey_t::raw.

Referenced by BSL_Crypto_AddRegistryKeyName(), mock_bpa_key_registry_cosekey_decode(), mock_bpa_key_registry_init_jwk(), test_AppendixA_Example1_BIB_Source(), test_AppendixA_Example1_BIB_VerifyAccept(), test_AppendixA_Example4_BCB_Source(), test_AppendixA_Example4_BCB_VerifyAccept(), test_AppendixA_Example5_BCB_Source(), test_AppendixA_Example5_BCB_VerifyAccept(), test_AppendixA_Example6_BCB_Source(), test_CCSDS_Example_Mac_Source(), test_CCSDS_Example_Mac_VerifyAccept(), and test_key_stats().

◆ BSL_Crypto_ReleaseKeyHandle()

void BSL_Crypto_ReleaseKeyHandle ( BSL_Crypto_KeyHandle_t keyhandle )

Release a key handle after it is done being used.

Parameters

[in] keyhandle key handle to release. If the handle is null this does nothing.

Postcondition: If this is the last use of the handle (including the key registry) the key will be destroyed.

References keyhandle.

Referenced by BSL_Crypto_AddRegistryKeyName(), BSLX_BCB_Decrypt(), BSLX_BCB_Encrypt(), BSLX_BIB_GenHMAC(), BSLX_CoseSc_Deinit(), mock_bpa_key_registry_cosekey_decode(), mock_bpa_key_registry_init_jwk(), test_AppendixA_Example1_BIB_Source(), test_AppendixA_Example1_BIB_VerifyAccept(), test_AppendixA_Example4_BCB_Source(), test_AppendixA_Example4_BCB_VerifyAccept(), test_AppendixA_Example5_BCB_Source(), test_AppendixA_Example5_BCB_VerifyAccept(), test_AppendixA_Example6_BCB_Source(), test_CCSDS_Example_Mac_Source(), and test_CCSDS_Example_Mac_VerifyAccept().

◆ BSL_Crypto_RemoveRegistryKey()

int BSL_Crypto_RemoveRegistryKey ( const BSL_Data_t * keyid )

Erase key entry from crypto library registry, if present.

Parameters

[in] keyid key ID of key to remove.

Returns: Zero if the key was present.

References ASSERT_ARG_NONNULL, BSL_SUCCESS, keyid, StaticCryptoMutex, and StaticKeyRegistry.

Referenced by BSL_Crypto_RemoveRegistryKeyName().

◆ BSL_Crypto_SetKeyParameter()

BSL_IdValPair_t * BSL_Crypto_SetKeyParameter	(	BSL_Crypto_KeyHandle_t	handle,
		int64_t	param_id
	)

Add a context-specific parameter to a known key.

Parameters

[in]	handle	The key ID to update.
[in]	param_id	The parameter to access. If the parameter does not already exist it will be created.

Returns: Non-NULL pointer if successful.

References ASSERT_ARG_NONNULL, and BSL_CryptoKey_t::params.

Referenced by mock_bpa_key_registry_cosekey_decode(), test_AppendixA_Example1_BIB_Source(), test_AppendixA_Example1_BIB_VerifyAccept(), test_AppendixA_Example4_BCB_Source(), test_AppendixA_Example4_BCB_VerifyAccept(), test_AppendixA_Example5_BCB_Source(), test_AppendixA_Example5_BCB_VerifyAccept(), test_AppendixA_Example6_BCB_Source(), test_CCSDS_Example_Mac_Source(), and test_CCSDS_Example_Mac_VerifyAccept().

◆ 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 main(), test_AppendixA_Example5_BCB_Source(), test_AppendixA_Example6_BCB_Source(), test_CCSDS_Example_Mac_Source(), test_RFC9173_AppendixA_Example1_BIB_Source(), test_RFC9173_AppendixA_Example2_BCB_Source(), test_RFC9173_AppendixA_Example3_Acceptor(), test_RFC9173_AppendixA_Example4_Acceptor(), test_RFC9173_AppendixA_Example4_Source(), test_sec_accept_keyunwrap(), and test_sec_source_keywrap().

◆ BSL_Crypto_UnwrapKey()

int BSL_Crypto_UnwrapKey	(	BSL_Crypto_KeyHandle_t	kek_handle,
		const BSL_Data_t *	wrapped_key,
		BSL_Crypto_KeyHandle_t *	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.

References ASSERT_ARG_NONNULL, BSL_CRYPTO_KEYSTATS_BYTES_PROCESSED, BSL_CRYPTO_KEYSTATS_TIMES_USED, BSL_Data_AppendFrom(), BSL_Data_Resize(), BSL_ERR_SECURITY_CONTEXT_CRYPTO_FAILED, BSL_LOG_DEBUG, BSL_LOG_ERR, BSL_LOG_PLAINTEXT_PTR, CHK_PROPERTY, ctx, BSL_Data_t::len, BSL_Data_t::ptr, BSL_CryptoKey_t::raw, BSL_CryptoKey_t::stats, BSL_Crypto_KeyStats_t::stats, and BSL_CryptoKey_t::stats_mutex.

Referenced by BSLX_BCB_Decrypt(), BSLX_BIB_GenHMAC(), and BSLX_CoseSc_ExtractContentKey().

◆ BSL_Crypto_WrapKey()

int BSL_Crypto_WrapKey	(	BSL_Crypto_KeyHandle_t	kek_handle,
		BSL_Crypto_KeyHandle_t	cek_handle,
		BSL_Data_t *	wrapped_key
	)

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

References BSL_CRYPTO_KEYSTATS_BYTES_PROCESSED, BSL_CRYPTO_KEYSTATS_TIMES_USED, BSL_Data_AppendFrom(), BSL_Data_Resize(), BSL_ERR_SECURITY_CONTEXT_CRYPTO_FAILED, BSL_LOG_DEBUG, BSL_LOG_ERR, BSL_LOG_PLAINTEXT_PTR, CHK_ARG_NONNULL, ctx, BSL_Data_t::len, BSL_Data_t::ptr, BSL_CryptoKey_t::raw, BSL_CryptoKey_t::stats, BSL_Crypto_KeyStats_t::stats, and BSL_CryptoKey_t::stats_mutex.

Referenced by BSLX_BCB_Encrypt(), BSLX_BIB_GenHMAC(), BSLX_CoseSc_GenerateContentKey(), and TEST_CASE().

◆ BSL_CryptoDeinit()

void BSL_CryptoDeinit ( void )

Deinitialize the crypto subsystem.

This should be called at the end of the process.

References StaticCryptoMutex, and StaticKeyRegistry.

Referenced by _tearDown(), LLVMFuzzerTestOneInput(), main(), and tearDown().

◆ BSL_CryptoInit()

void BSL_CryptoInit ( void )

Initialize the crypto subsystem.

This must be called once per process.

References rand_bytes_generator, StaticCryptoMutex, and StaticKeyRegistry.

Referenced by _setUp(), LLVMFuzzerTestOneInput(), main(), and setUp().

◆ BSL_CryptoKey_Deinit()

static void BSL_CryptoKey_Deinit ( BSL_CryptoKey_t * key )

static

References ASSERT_ARG_NONNULL, BSL_CRYPTO_KEYSTATS_MAX_INDEX, BSL_Data_Deinit(), BSL_CryptoKey_t::params, BSL_CryptoKey_t::raw, BSL_CryptoKey_t::stats, BSL_Crypto_KeyStats_t::stats, and BSL_CryptoKey_t::stats_mutex.

◆ BSL_CryptoKey_Init()

static void BSL_CryptoKey_Init ( BSL_CryptoKey_t * key )

static

References ASSERT_ARG_NONNULL, BSL_CRYPTO_KEYSTATS_MAX_INDEX, BSL_Data_Init(), BSL_CryptoKey_t::params, BSL_CryptoKey_t::raw, BSL_CryptoKey_t::stats, BSL_Crypto_KeyStats_t::stats, and BSL_CryptoKey_t::stats_mutex.

Variable Documentation

◆ BSL_Crypto_zero

const uint8_t BSL_Crypto_zero = 0

static

◆ rand_bytes_generator

BSL_Crypto_RandBytesFn rand_bytes_generator

static

Random bytes generator.

Referenced by BSL_Crypto_GenIV(), BSL_Crypto_GenKey(), BSL_Crypto_SetRngGenerator(), and BSL_CryptoInit().

◆ StaticCryptoMutex

pthread_mutex_t StaticCryptoMutex = PTHREAD_MUTEX_INITIALIZER

static

Referenced by BSL_Crypto_AddRegistryKey(), BSL_Crypto_GetRegistryKey(), BSL_Crypto_RemoveRegistryKey(), BSL_CryptoDeinit(), and BSL_CryptoInit().

◆ StaticKeyRegistry

BSL_CryptoKeyDict_t StaticKeyRegistry

static

Crypto key registry.

Referenced by BSL_Crypto_AddRegistryKey(), BSL_Crypto_GetRegistryKey(), BSL_Crypto_RemoveRegistryKey(), BSL_CryptoDeinit(), and BSL_CryptoInit().

Data Structures

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ BSL_Crypto_PtrOrZero

◆ M_OPL_BSL_CryptoKey_t

Function Documentation

◆ BSL_AuthCtx_Deinit()

◆ BSL_AuthCtx_DigestBuffer()

◆ BSL_AuthCtx_DigestSeq()

◆ BSL_AuthCtx_Finalize()

◆ BSL_AuthCtx_Init()

◆ BSL_Cipher_AddAadBuffer()

◆ BSL_Cipher_AddAadSeq()

◆ BSL_Cipher_AddSeq()

◆ BSL_Cipher_Deinit()

◆ BSL_Cipher_FinalizeSeq()

◆ BSL_Cipher_GetTag()

◆ BSL_Cipher_Init()

◆ BSL_Cipher_SetTag()

◆ BSL_Cipher_TagLen()

◆ BSL_Crypto_AddRegistryKey()

◆ BSL_Crypto_Compare()

◆ BSL_Crypto_CompareKeys()

◆ BSL_Crypto_GenIV()

◆ BSL_Crypto_GenKey()

◆ BSL_Crypto_GetKeyParameter()

◆ BSL_Crypto_GetKeyStatistics()

◆ BSL_Crypto_GetRegistryKey()

◆ BSL_Crypto_KDF()

◆ BSL_Crypto_LoadKey()

◆ BSL_Crypto_ReleaseKeyHandle()

◆ BSL_Crypto_RemoveRegistryKey()

◆ BSL_Crypto_SetKeyParameter()

◆ BSL_Crypto_SetRngGenerator()

◆ BSL_Crypto_UnwrapKey()

◆ BSL_Crypto_WrapKey()

◆ BSL_CryptoDeinit()

◆ BSL_CryptoInit()

◆ BSL_CryptoKey_Deinit()

◆ BSL_CryptoKey_Init()

Variable Documentation

◆ BSL_Crypto_zero

◆ rand_bytes_generator

◆ StaticCryptoMutex

◆ StaticKeyRegistry