Abstract interface for crypto processing. More...

#include "bsl/BPSecLib_Private.h"
#include "bsl/BSLConfig.h"
#include "bsl/front/Data.h"
#include "bsl/front/SeqReader.h"
#include "bsl/front/SeqWriter.h"
#include <stdint.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_Cipher_t
	Struct def for cipher operation context. More...

struct	BSL_AuthCtx_t
	Struct def for HMAC operation context. More...

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

typedef void *	BSL_Crypto_LibHandle_t
	Opaque handle for backend library objects for stateful processing.

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.

int	BSL_Crypto_GenIV (BSL_Data_t *buf)
	Generate random bytes.

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.

AES Key Wrap interface
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_UnwrapKey (BSL_Crypto_KeyHandle_t kek_handle, const BSL_Data_t wrapped_key, BSL_Crypto_KeyHandle_t cek_handle)
	Perform key unwrap.

Key registry interface
There are two forms of managed crypto keys in this interface: Identified keys persisted in a long-term, thread-safe registry. These keys have byte string names (which can contain UTF8 text) and can have additional parameters to restrict their use. Anonymous ephemeral keys used for individual operations and then discarded. These keys do not have names and are typically key-wrapped or the result of a key derivation function (KDF).
enum	BSL_Crypto_KeyStatCounterIndex_t { BSL_CRYPTO_KEYSTATS_TIMES_USED = 0 , BSL_CRYPTO_KEYSTATS_BYTES_PROCESSED , BSL_CRYPTO_KEYSTATS_MAX_INDEX }

typedef struct BSL_CryptoKeyPtr_s *	BSL_Crypto_KeyHandle_t
	Opaque handle for key objects in the key store.

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.

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_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_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_GetKeyStatistics (BSL_Crypto_KeyHandle_t handle, BSL_Crypto_KeyStats_t *stats)
	Retrieve statistics related to a crypto key.

Key Derivation Function (KDF) interface
enum	BSL_Crypto_KDFVariant_t { BSL_CRYPTO_KDF_HKDF_SHA_256 , BSL_CRYPTO_KDF_HKDF_SHA_512 }

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.

Confidentiality cipher interface
Cipher 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_AddAadBuffer() or BSL_Cipher_AddAadSeq() 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_AddAadBuffer() or BSL_Cipher_AddAadSeq() 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()
enum	BSL_CipherMode_e { BSL_CRYPTO_ENCRYPT , BSL_CRYPTO_DECRYPT }
	Enum def to define cipher contexts as encryption or decryption operations. More...

enum	BSL_Crypto_AESVariant_e { BSL_CRYPTO_AES_128 , BSL_CRYPTO_AES_192 , BSL_CRYPTO_AES_256 }
	Choice of fully-specified cipher algorithm. More...

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.

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.

Integrity MAC interface
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()
enum	BSL_Crypto_SHAVariant_e { BSL_CRYPTO_SHA_256 , BSL_CRYPTO_SHA_384 , BSL_CRYPTO_SHA_512 }
	Choice of fully-specified MAC algorithm. More...

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

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

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

Detailed Description

Abstract interface for crypto processing.

This file is organized into groups based on topic: key registry, HMAC, cipher, etc.

Typedef Documentation

◆ BSL_Crypto_KeyHandle_t

typedef struct BSL_CryptoKeyPtr_s* BSL_Crypto_KeyHandle_t

Opaque handle for key objects in the key store.

◆ BSL_Crypto_LibHandle_t

typedef void* BSL_Crypto_LibHandle_t

Opaque handle for backend library objects for stateful processing.

◆ 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	Encrypt from plaintext to ciphertext.
BSL_CRYPTO_DECRYPT	Decrypt from ciphertext to plaintext.

◆ BSL_Crypto_AESVariant_e

enum BSL_Crypto_AESVariant_e

Choice of fully-specified cipher algorithm.

Enumerator
BSL_CRYPTO_AES_128	AES-GCM with 128-bit key.
BSL_CRYPTO_AES_192	AES-GCM with 192-bit key.
BSL_CRYPTO_AES_256	AES-GCM with 256-bit key.

◆ BSL_Crypto_KDFVariant_t

enum BSL_Crypto_KDFVariant_t

Enumerator
BSL_CRYPTO_KDF_HKDF_SHA_256
BSL_CRYPTO_KDF_HKDF_SHA_512

◆ BSL_Crypto_KeyStatCounterIndex_t

enum BSL_Crypto_KeyStatCounterIndex_t

Enumerator
BSL_CRYPTO_KEYSTATS_TIMES_USED
BSL_CRYPTO_KEYSTATS_BYTES_PROCESSED
BSL_CRYPTO_KEYSTATS_MAX_INDEX	Not a real index, used to size arrays.

◆ BSL_Crypto_SHAVariant_e

enum BSL_Crypto_SHAVariant_e

Choice of fully-specified MAC algorithm.

Enumerator
BSL_CRYPTO_SHA_256	HMAC SHA2-256 with 256-bit key.
BSL_CRYPTO_SHA_384	HMAC SHA2-384 with 384-bit key.
BSL_CRYPTO_SHA_512	HMAC SHA2-512 with 512-bit key.

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()

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, 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()

BSL_REQUIRE_CHECK 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().

Data Structures

Typedefs

Functions

Key registry interface

Key Derivation Function (KDF) interface

Confidentiality cipher interface

Integrity MAC interface

Detailed Description

Typedef Documentation

◆ BSL_Crypto_KeyHandle_t

◆ BSL_Crypto_LibHandle_t

◆ BSL_Crypto_RandBytesFn

Enumeration Type Documentation

◆ BSL_CipherMode_e

◆ BSL_Crypto_AESVariant_e

◆ BSL_Crypto_KDFVariant_t

◆ BSL_Crypto_KeyStatCounterIndex_t

◆ BSL_Crypto_SHAVariant_e

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()