KeyStore.h File Reference

There are two forms of managed crypto keys in this interface: More...

#include "bsl/BPSecLib_Private.h"
#include "bsl/front/Data.h"
#include <stdint.h>

Include dependency graph for KeyStore.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_KeyStore_Descriptors_t
	The set of callback function pointers which actually implement a key store. More...

Typedefs
typedef void *	BSL_Crypto_KeyHandle_t
	Opaque handle for key objects in the key store.

Enumerations
enum	BSL_Crypto_KeyStats_CounterIndex_t { BSL_CRYPTO_KEYSTATS_TIMES_USED = 0 , BSL_CRYPTO_KEYSTATS_BYTES_PROCESSED , BSL_CRYPTO_KEYSTATS_MAX_INDEX }
	Indices of telemetry counters in BSL_Crypto_KeyStats_t. More...

Functions
int	BSL_KeyStore_Init (BSL_KeyStore_Descriptors_t desc)
	Initialize the key store subsystem.
void	BSL_KeyStore_Deinit (void)
	Deinitialize the key store subsystem.
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 *handle)
	Get pointers to an existing key, if present.
const BSL_Variant_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.

Detailed Description

There are two forms of managed crypto keys in this interface:

1. 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.
2. 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).

Typedef Documentation

BSL_Crypto_KeyHandle_t

typedef void* BSL_Crypto_KeyHandle_t

Opaque handle for key objects in the key store.

Enumeration Type Documentation

BSL_Crypto_KeyStats_CounterIndex_t

enum BSL_Crypto_KeyStats_CounterIndex_t

Indices of telemetry counters in BSL_Crypto_KeyStats_t.

Enumerator
BSL_CRYPTO_KEYSTATS_TIMES_USED	Incremented once per use.
BSL_CRYPTO_KEYSTATS_BYTES_PROCESSED	Incremented for each byte processed. The specific meaning depends on the algorithm associated with the key.
BSL_CRYPTO_KEYSTATS_MAX_INDEX	Not a real index, used to size arrays.

Function Documentation

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 ASSERT_PRECONDITION, BSL_Crypto_Compare(), BSL_KeyStore_State, BSL_SUCCESS, CHK_AS_BOOL, BSL_KeyStore_Descriptors_t::get_keymat, BSL_Data_t::len, and BSL_Data_t::ptr.

Referenced by TEST_CASE().

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_Crypto_GenIV(), BSL_Crypto_LoadKey(), BSL_Data_Deinit(), BSL_Data_InitBuffer(), BSL_ERR_FAILURE, BSL_SUCCESS, CHK_ARG_EXPR, CHK_ARG_NONNULL, BSL_Data_t::len, and BSL_Data_t::ptr.

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

BSL_Crypto_GetKeyParameter()

const BSL_Variant_t * BSL_Crypto_GetKeyParameter	(	BSL_Crypto_KeyHandle_t	handle,
		int64_t	param_id
	)

Get key parameter for read-only access.

Parameters

[in]	handle	The handle to the key.
	param_id	The unique identifier for the parameter. The available parameters will be determined by the key source (e.g. COSE_Key parameters).

Returns

A non-null pointer if the parameter exists.

References ASSERT_PRECONDITION, BSL_KeyStore_State, and BSL_KeyStore_Descriptors_t::get_parameter.

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_PRECONDITION, BSL_KeyStore_State, CHK_ARG_NONNULL, BSL_KeyStore_Descriptors_t::find_key, and BSL_KeyStore_Descriptors_t::get_stats.

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 *	handle
	)

Get pointers to an existing key, if present.

Parameters

	keyid	The key to search for.
[in,out]	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_PRECONDITION, BSL_KeyStore_State, CHK_ARG_NONNULL, BSL_KeyStore_Descriptors_t::find_key, and keyid.

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

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. This applies even to cases where this function fails but still sets key_out non-NULL.

Returns

BSL_SUCCESS if successful.

References ASSERT_PRECONDITION, BSL_DATA_INIT_VIEW, BSL_ERR_SECURITY_CONTEXT_CRYPTO_FAILED, BSL_KeyStore_State, BSL_LOG_ERR, BSL_SUCCESS, CHK_ARG_EXPR, CHK_ARG_NONNULL, BSL_KeyStore_Descriptors_t::new_key, and BSL_KeyStore_Descriptors_t::set_keymat.

Referenced by BSL_Crypto_AddRegistryKeyName(), BSL_Crypto_GenKey(), BSL_Crypto_KDF(), BSL_Crypto_KeyLoader_LoadCoseKeySet_decode(), BSL_Crypto_KeyLoader_LoadJwkSet(), BSL_Crypto_UnwrapKey(), 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 ASSERT_PRECONDITION, BSL_KeyStore_State, keyhandle, and BSL_KeyStore_Descriptors_t::release_key.

Referenced by BSL_Crypto_AddRegistryKeyName(), BSL_Crypto_KeyLoader_LoadCoseKeySet_decode(), BSL_Crypto_KeyLoader_LoadJwkSet(), BSLX_BCB_Decrypt(), BSLX_BCB_Encrypt(), BSLX_BIB_GenHMAC(), BSLX_CoseSc_Deinit(), 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_KeyStore_Deinit()

void BSL_KeyStore_Deinit

(

void

)

Deinitialize the key store subsystem.

This should be called at the end of the process.

Warning

This function is not thread safe and should be used after any BSL_LibCtx_s is deinitialized.

References BSL_KeyStore_Descriptors_EMPTY, and BSL_KeyStore_State.

Referenced by MockBPA_KeyStore_Deinit().

BSL_KeyStore_Init()

int BSL_KeyStore_Init

(

BSL_KeyStore_Descriptors_t

desc

)

Initialize the key store subsystem.

This must be called once per process.

Warning

This function is not thread safe and should be used before any BSL_LibCtx_s is initialized or other BSL interfaces used.

Parameters

desc	The descriptor to use for future key store access.

Returns

Zero if successful, negative on error.

References BSL_KeyStore_Descriptors_t::acquire_key, BSL_KeyStore_Descriptors_t::add_key, BSL_KeyStore_State, BSL_SUCCESS, CHK_PRECONDITION, BSL_KeyStore_Descriptors_t::find_key, BSL_KeyStore_Descriptors_t::get_keymat, BSL_KeyStore_Descriptors_t::get_parameter, BSL_KeyStore_Descriptors_t::get_stats, BSL_KeyStore_Descriptors_t::new_key, BSL_KeyStore_Descriptors_t::release_key, BSL_KeyStore_Descriptors_t::set_keymat, BSL_KeyStore_Descriptors_t::set_parameter, and BSL_KeyStore_Descriptors_t::update_stats.

Referenced by MockBPA_KeyStore_Init().