Implementation of the dynamic backend Public API. More...

#include <inttypes.h>
#include <BPSecLib_Private.h>
#include <BPSecLib_Public.h>
#include "PublicInterfaceImpl.h"
#include "SecurityActionSet.h"
#include "SecurityResultSet.h"

Include dependency graph for PublicInterfaceImpl.c:

Functions
char *	BSL_Log_DumpAsHexString (char dstbuf, size_t dstlen, const uint8_t srcbuf, size_t srclen)
	Helper function to print the ASCII encoding of a given byte stream to a given target buffer.

size_t	BSL_LibCtx_Sizeof (void)
	Return size of library context.

int	BSL_API_InitLib (BSL_LibCtx_t *lib)
	Initialize the BPSecLib (BSL) library context.

int	BSL_API_DeinitLib (BSL_LibCtx_t *lib)
	Deinitialize and release any resources held by the BSL.

int	BSL_LibCtx_AccumulateTlmCounters (const BSL_LibCtx_t lib, BSL_TlmCounters_t tlm)
	Retrieve copy of the telemetry counters to accumulate in BPA.

void	BSL_PrimaryBlock_deinit (BSL_PrimaryBlock_t *obj)
	Deinitialize the use of a primary block metadata.

int	BSL_API_RegisterSecurityContext (BSL_LibCtx_t *lib, uint64_t sec_ctx_id, BSL_SecCtxDesc_t desc)
	Register a security context module with the BSL.

int	BSL_API_RegisterPolicyProvider (BSL_LibCtx_t *lib, uint64_t pp_id, BSL_PolicyDesc_t desc)
	Register a Policy Provider module with the BSL.

int	BSL_API_QuerySecurity (const BSL_LibCtx_t bsl, BSL_SecurityActionSet_t output_action_set, const BSL_BundleRef_t *bundle, BSL_PolicyLocation_e location)
	Query BSL to populate a `BSL_SecurityActionSet_t` containing security processing instructions.

int	BSL_API_ApplySecurity (const BSL_LibCtx_t bsl, BSL_SecurityResponseSet_t response_output, BSL_BundleRef_t bundle, const BSL_SecurityActionSet_t policy_actions)
	Performs the given security operations on a Bundle, modifying or even dropping it entirely.

Detailed Description

Implementation of the dynamic backend Public API.

Todo:: MAJOR Complete implementation for ApplySecurity so it can drop blocks or bundles as-needed.

Function Documentation

◆ BSL_API_ApplySecurity()

int BSL_API_ApplySecurity	(	const BSL_LibCtx_t *	bsl,
		BSL_SecurityResponseSet_t *	response_output,
		BSL_BundleRef_t *	bundle,
		const BSL_SecurityActionSet_t *	policy_actions
	)

Performs the given security operations on a Bundle, modifying or even dropping it entirely.

Parameters

[in]	bsl	Pointer to BSL context structure.
[out]	response_output	Pointer to host-allocated output structure.
[in,out]	bundle	Reference to host-owned Bundle, which may be modified or dropped by the BSL.
[in]	policy_actions	Pointer to policy actions, which was populated using the `QuerySecurity` function.

References bsl, BSL_LOG_DEBUG, BSL_LOG_ERR, BSL_LOG_INFO, BSL_PolicyRegistry_FinalizeActions(), BSL_SecCtx_ExecutePolicyActionSet(), BSL_SECOP_CONCLUSION_SUCCESS, BSL_SecOper_GetConclusion(), BSL_SecurityAction_CountSecOpers(), BSL_SecurityAction_GetSecOperAtIndex(), BSL_SecurityResponseSet_Deinit(), BSL_SecurityResponseSet_Init(), BSL_SUCCESS, and CHK_ARG_NONNULL.

Referenced by MockBPA_Agent_process(), n_test_BSL_6(), test_BSL_32(), TEST_CASE(), and test_dyn_mem_cbs_BSL_32().

◆ BSL_API_DeinitLib()

int BSL_API_DeinitLib ( BSL_LibCtx_t * bsl )

Deinitialize and release any resources held by the BSL.

Note: This only needs to be run once per lifetime of the BSL.

Parameters

[in,out] bsl Pointer to library context

Returns: 0 on success, negative on error.

References BSL_LOG_WARNING, BSL_SUCCESS, and CHK_ARG_NONNULL.

Referenced by _tearDown(), MockBPA_Agent_Deinit(), and tearDown().

◆ BSL_API_InitLib()

int BSL_API_InitLib ( BSL_LibCtx_t * bsl )

Initialize the BPSecLib (BSL) library context.

Note: This only needs to be done once per lifetime of the BSL.

Parameters

[in,out] bsl Pointer to allocated space for the library context.

Returns: 0 on success, negative on error.

References BSL_SUCCESS, and CHK_ARG_NONNULL.

Referenced by _setUp(), MockBPA_Agent_Init(), and setUp().

◆ BSL_API_QuerySecurity()

int BSL_API_QuerySecurity	(	const BSL_LibCtx_t *	bsl,
		BSL_SecurityActionSet_t *	output_action_set,
		const BSL_BundleRef_t *	bundle,
		BSL_PolicyLocation_e	location
	)

Query BSL to populate a BSL_SecurityActionSet_t containing security processing instructions.

This executes a chain of events in the BSL. First by querying the policy provider, then checking with the security context for viability. It returns 0 and a populated BSL_SecurityActionSet_ with the security operations and their parameters, if successful.

Note: A BSL guideline is that caller's generally allocate the memory for callee's. In this case, the BPA must create space for the output action set using _Sizeof functions for the respective structures.

Parameters

[in]	bsl	Pointer to BSL context.
[in,out]	output_action_set	Pointer to pre-allocated structure into which security operations will be populated.
[in]	bundle	Reference to BPA-owned bundle.
[in]	location	"Location" within the BPA (e.g,. "At app egress")

Returns: 0 on success, negative on error. On zero, output_action_set will be populated.

References BSL_PrimaryBlock_t::block_count, BSL_CanonicalBlock_t::block_num, BSL_PrimaryBlock_t::block_numbers, bsl, BSL_AbsSecBlock_ContainsTarget(), BSL_AbsSecBlock_DecodeFromCBOR(), BSL_AbsSecBlock_Deinit(), BSL_AbsSecBlock_InitEmpty(), BSL_AbsSecBlock_Sizeof(), BSL_BundleCtx_GetBlockMetadata(), BSL_BundleCtx_GetBundleMetadata(), BSL_BundleCtx_ReadBTSD(), BSL_calloc(), BSL_Data_Deinit(), BSL_Data_InitBuffer(), BSL_ERR_HOST_CALLBACK_FAILED, BSL_ERR_SECURITY_CONTEXT_VALIDATION_FAILED, BSL_free(), BSL_LOG_ERR, BSL_LOG_INFO, BSL_LOG_WARNING, BSL_PolicyRegistry_InspectActions(), BSL_PrimaryBlock_deinit(), BSL_REASONCODE_BLOCK_UNINTELLIGIBLE, BSL_SecCtx_ValidatePolicyActionSet(), BSL_SecOper_SetReasonCode(), BSL_SecurityAction_CountSecOpers(), BSL_SecurityAction_GetSecOperAtIndex(), BSL_SecurityActionSet_Init(), BSL_SeqReader_Destroy(), BSL_SeqReader_Get(), BSL_SUCCESS, BSL_TLM_BUNDLE_INSPECTED_COUNT, BSL_TlmCounters_IncrementCounter(), BSL_CanonicalBlock_t::btsd_len, CHK_ARG_NONNULL, BSL_Data_t::len, BSL_Data_t::ptr, and BSL_CanonicalBlock_t::type_code.

Referenced by MockBPA_Agent_process(), n_test_BSL_6(), test_BSL_32(), TEST_CASE(), and test_dyn_mem_cbs_BSL_32().

◆ BSL_API_RegisterPolicyProvider()

int BSL_API_RegisterPolicyProvider	(	BSL_LibCtx_t *	lib,
		uint64_t	pp_id,
		BSL_PolicyDesc_t	desc
	)

Register a Policy Provider module with the BSL.

Note: The Policy Provider interface is defined by the policy provider descriptor.

Parameters

[in,out]	lib	Pointer to BSL context.
[in]	desc	Policy Provider callbacks.

References BSL_SUCCESS, CHK_ARG_EXPR, and CHK_ARG_NONNULL.

Referenced by _setUp(), MockBPA_Agent_Init(), setUp(), and test_MultiplePolicyProviders().

◆ BSL_API_RegisterSecurityContext()

int BSL_API_RegisterSecurityContext	(	BSL_LibCtx_t *	lib,
		uint64_t	sec_ctx_id,
		BSL_SecCtxDesc_t	desc
	)

Register a security context module with the BSL.

Note: The Security Context interface is defined by the security context descriptor.

Parameters

[in,out]	lib	Pointer to BSL context.
[in]	sec_ctx_id	Security context ID
[in]	desc	Descriptor struct containing callbacks.

References BSL_SUCCESS, CHK_ARG_EXPR, and CHK_ARG_NONNULL.

Referenced by BSL_TestUtils_SetupDefaultSecurityContext(), and MockBPA_Agent_Init().

◆ BSL_LibCtx_AccumulateTlmCounters()

int BSL_LibCtx_AccumulateTlmCounters	(	const BSL_LibCtx_t *	lib,
		BSL_TlmCounters_t *	tlm
	)

Retrieve copy of the telemetry counters to accumulate in BPA.

Parameters

[in]	lib	Pointer to BSL context.
[out]	sec_ctx_id	Pointer to the output telemetry structure

Returns: 0 on success, negative on error.

References BSL_SUCCESS, CHK_ARG_NONNULL, and BSL_TlmCounters_t::counters.

Referenced by MockBPA_Agent_DumpTelemetry().

◆ BSL_LibCtx_Sizeof()

size_t BSL_LibCtx_Sizeof ( void )

Return size of library context.

Referenced by MockBPA_Agent_Init().

◆ BSL_Log_DumpAsHexString()

char * BSL_Log_DumpAsHexString	(	char *	dstbuf,
		size_t	dstlen,
		const uint8_t *	srcbuf,
		size_t	srclen
	)

Helper function to print the ASCII encoding of a given byte stream to a given target buffer.

Todo:

Can be moved to backend.

Parameters

dstbuf	Pointer to a buffer where the C string should go.
dstlen	The length in bytes of `dstbuf`
srcbuf	Pointer to the buffer containing the byte stream to be printed.
srclen	The length in bytes of `srcbuf`.