Single entry-point include file for all of the "Public" BPSec Lib (BSL) frontend API. More...

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include "BSLConfig.h"
#include "Data.h"

Include dependency graph for BPSecLib_Public.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	BSL_TlmCounters_t
	The telemetry counter structure to store the enumerations of telemetry. More...

struct	BSL_HostEID_t
	Opaque pointer to BPA-specific Endpoint ID storage. More...

struct	BSL_HostEIDPattern_t
	Reference to a EID pattern owned and stored in the BPA. More...

struct	BSL_BundleRef_t
	Reference to a Bundle owned and stored in the host BPA. More...

struct	BSL_PrimaryBlock_t
	Contains Bundle Primary Block fields and metadata. More...

struct	BSL_CanonicalBlock_t
	Structure containing parsed Canonical Block fields. More...

struct	BSL_HostDescriptors_t
	Dynamic BPA descriptor. More...

Macros
#define	BSL_REQUIRE_CHECK
	This annotation on a function requires the caller to capture and inspect the return value.

#define	BSL_TLM_COUNTERS_ZERO

Enumerations
enum	BSL_PolicyLocation_e { BSL_POLICYLOCATION_APPIN = 101 , BSL_POLICYLOCATION_APPOUT , BSL_POLICYLOCATION_CLIN , BSL_POLICYLOCATION_CLOUT }
	Indicates where in the lifecycle of the BPA the bundle is querying for security policy. More...

enum	BSL_SecOper_ConclusionState_e { BSL_SECOP_CONCLUSION_PENDING = 1 , BSL_SECOP_CONCLUSION_SUCCESS , BSL_SECOP_CONCLUSION_INVALID , BSL_SECOP_CONCLUSION_FAILURE }
	Indicates the conclusion state of a security operation. More...

enum	BSL_BundleCRCType_e { BSL_BUNDLECRCTYPE_NONE = 0 , BSL_BUNDLECRCTYPE_16 = 1 , BSL_BUNDLECRCTYPE_32 = 2 }
	Block CRC types. More...

enum	BSL_TlmCounterIndex_e { BSL_TLM_BUNDLE_INSPECTED_COUNT = 0 , BSL_TLM_BUNDLE_INSPECTED_BYTES , BSL_TLM_ASB_DECODE_COUNT , BSL_TLM_ASB_DECODE_BYTES , BSL_TLM_ASB_ENCODE_COUNT , BSL_TLM_ASB_ENCODE_BYTES , BSL_TLM_SECOP_SOURCE_COUNT , BSL_TLM_SECOP_VERIFIER_COUNT , BSL_TLM_SECOP_ACCEPTOR_COUNT , BSL_TLM_SECOP_FAIL_COUNT , BSL_TLM_TOTAL_COUNT }
	Defined indices for the counter structure to hold telemetry and counts. More...

enum	BSL_ReasonCode_t { BSL_REASONCODE_NO_ADDITIONAL_INFO = 0 , BSL_REASONCODE_LIFETIME_EXPIRED = 1 , BSL_REASONCODE_FWD_UNIDIRECT_LINK = 2 , BSL_REASONCODE_TX_CANCEL = 3 , BSL_REASONCODE_DEPLETED_STORAGE = 4 , BSL_REASONCODE_DEST_EID_UNAVAILABLE = 5 , BSL_REASONCODE_NO_KNOWN_ROUTE = 6 , BSL_REASONCODE_NO_CONTACT_NEXT_NODE = 7 , BSL_REASONCODE_BLOCK_UNINTELLIGIBLE = 8 , BSL_REASONCODE_HOP_LIMIT_EXCEEDED = 9 , BSL_REASONCODE_TRAFFIC_PARED = 10 , BSL_REASONCODE_BLOCK_UNSUPPORTED = 11 , BSL_REASONCODE_MISSING_SECOP = 12 , BSL_REASONCODE_UNKNOWN_SECOP = 13 , BSL_REASONCODE_UNEXPECTED_SECOP = 14 , BSL_REASONCODE_FAILED_SECOP = 15 , BSL_REASONCODE_CONFLICTING_SECOP = 16 }
	IANA "Bundle Status Report Reason Codes" registry [6] [3]. More...

Functions
size_t	BSL_LibCtx_Sizeof (void)
	Return size of library context.

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_HostDescriptors_Set (BSL_HostDescriptors_t desc)
	Set the BPA descriptor (callbacks) for this process.

void	BSL_HostDescriptors_Get (BSL_HostDescriptors_t *desc)
	Copy the BPA descriptor for this process.

void	BSL_HostDescriptors_Clear (void)
	Reset the host descriptors to their default, unusable state.

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

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

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

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

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

BSL_REQUIRE_CHECK 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

Single entry-point include file for all of the "Public" BPSec Lib (BSL) frontend API.

This contains the interface for the BPA.

Author: Bill..nosp@m.Van..nosp@m.Besie.nosp@m.n@jh.nosp@m.uapl..nosp@m.edu

Macro Definition Documentation

◆ BSL_TLM_COUNTERS_ZERO

#define BSL_TLM_COUNTERS_ZERO

Value:

    (BSL_TlmCounters_t)       \
    {                         \
        0                     \
    }

Enumeration Type Documentation

◆ BSL_BundleCRCType_e

enum BSL_BundleCRCType_e

Block CRC types.

Defined in Section 4.2.1 of RFC 9171 [6].

Enumerator
BSL_BUNDLECRCTYPE_NONE	No CRC value.
BSL_BUNDLECRCTYPE_16	CRC-16.
BSL_BUNDLECRCTYPE_32	CRC-32C.

◆ BSL_PolicyLocation_e

enum BSL_PolicyLocation_e

Indicates where in the lifecycle of the BPA the bundle is querying for security policy.

Note: The numeric values of the enum are arbitrary. We avoid using 0 as defaults.

Enumerator
BSL_POLICYLOCATION_APPIN	Bundle source at creation.
BSL_POLICYLOCATION_APPOUT	Bundle destination at delivery.
BSL_POLICYLOCATION_CLIN	Bundle ingress from CLA.
BSL_POLICYLOCATION_CLOUT	Bundle egress to CLA.

◆ BSL_ReasonCode_t

enum BSL_ReasonCode_t

IANA "Bundle Status Report Reason Codes" registry [6] [3].

Enumerator
BSL_REASONCODE_LIFETIME_EXPIRED	No additional information.
BSL_REASONCODE_FWD_UNIDIRECT_LINK	Lifetime expired.
BSL_REASONCODE_TX_CANCEL	Forwarded over unidirectional link.
BSL_REASONCODE_DEPLETED_STORAGE	Transmission canceled.
BSL_REASONCODE_DEST_EID_UNAVAILABLE	Depleted storage.
BSL_REASONCODE_NO_KNOWN_ROUTE	Destination endpoint ID unavailable.
BSL_REASONCODE_NO_CONTACT_NEXT_NODE	No known route to destination from here.
BSL_REASONCODE_BLOCK_UNINTELLIGIBLE	No timely contact with next node on route.
BSL_REASONCODE_HOP_LIMIT_EXCEEDED	Block unintelligible.
BSL_REASONCODE_TRAFFIC_PARED	Hop limit exceeded.
BSL_REASONCODE_BLOCK_UNSUPPORTED	Traffic pared.
BSL_REASONCODE_MISSING_SECOP	Block unsupported.
BSL_REASONCODE_UNKNOWN_SECOP	Missing security operation.
BSL_REASONCODE_UNEXPECTED_SECOP	Unknown security operation.
BSL_REASONCODE_FAILED_SECOP	Unexpected security operation.
BSL_REASONCODE_CONFLICTING_SECOP	Failed security operation.

◆ BSL_SecOper_ConclusionState_e

enum BSL_SecOper_ConclusionState_e

Indicates the conclusion state of a security operation.

Enumerator
BSL_SECOP_CONCLUSION_PENDING	Security operation is still pending action.
BSL_SECOP_CONCLUSION_SUCCESS	Security operation has concluded and succeeded.
BSL_SECOP_CONCLUSION_INVALID	Security operation is invalid.
BSL_SECOP_CONCLUSION_FAILURE	Security operation has concluded and failed.

◆ BSL_TlmCounterIndex_e

enum BSL_TlmCounterIndex_e

Defined indices for the counter structure to hold telemetry and counts.

Note: If more telemetry is added, the array in BSL_TlmCounters_t must be updated.

Function Documentation

◆ BSL_API_ApplySecurity()

BSL_REQUIRE_CHECK 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_LOG_DEBUG, BSL_LOG_ERR, BSL_LOG_INFO, BSL_PolicyRegistry_FinalizeActions(), BSL_SecCtx_ExecutePolicyActionSet(), BSL_SECOP_CONCLUSION_SUCCESS, BSL_SecOper_GetConclusion(), BSL_SecurityResponseSet_Deinit(), BSL_SecurityResponseSet_Init(), and BSL_SUCCESS.

Referenced by MockBPA_Agent_process().

◆ BSL_API_DeinitLib()

BSL_REQUIRE_CHECK 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, and BSL_SUCCESS.

Referenced by MockBPA_Agent_Deinit().

◆ BSL_API_InitLib()

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

Referenced by MockBPA_Agent_Init().

◆ BSL_API_QuerySecurity()

BSL_REQUIRE_CHECK 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_AbsSecBlock_ContainsTarget(), BSL_AbsSecBlock_DecodeFromCBOR(), BSL_AbsSecBlock_Deinit(), BSL_AbsSecBlock_InitEmpty(), BSL_AbsSecBlock_Sizeof(), BSL_BundleCtx_GetBlockMetadata(), BSL_BundleCtx_GetBundleMetadata(), 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_SecurityActionSet_Init(), BSL_SeqReader_Destroy(), BSL_SeqReader_Get(), BSL_SUCCESS, BSL_TlmCounters_IncrementCounter(), BSL_CanonicalBlock_t::btsd_len, BSL_Data_t::len, BSL_Data_t::ptr, and BSL_CanonicalBlock_t::type_code.

Referenced by MockBPA_Agent_process().

◆ BSL_API_RegisterPolicyProvider()

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

Referenced by MockBPA_Agent_Init(), and test_MultiplePolicyProviders().

◆ BSL_API_RegisterSecurityContext()

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

Referenced by MockBPA_Agent_Init().

◆ BSL_HostDescriptors_Clear()

void BSL_HostDescriptors_Clear ( void )

Reset the host descriptors to their default, unusable state.

Warning: This function is not thread safe and should be used after any ::BSL_LibCtx_t is deinitialized.

Referenced by main().

◆ BSL_HostDescriptors_Get()

void BSL_HostDescriptors_Get ( BSL_HostDescriptors_t * desc )

Copy the BPA descriptor for this process.

Note: This function is not thread safe.

Parameters

[out] desc The descriptor to copy into.

◆ BSL_HostDescriptors_Set()

int BSL_HostDescriptors_Set ( BSL_HostDescriptors_t desc )

Set the BPA descriptor (callbacks) for this process.

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

Parameters

desc	The descriptor to use for future BPA functions.

Returns: Zero if successful, negative on error.

Referenced by main().

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

Referenced by MockBPA_Agent_DumpTelemetry().

◆ BSL_PrimaryBlock_deinit()

void BSL_PrimaryBlock_deinit ( BSL_PrimaryBlock_t * obj )

Deinitialize the use of a primary block metadata.

Parameters

[in,out] obj The instance to deinit.

References BSL_PrimaryBlock_t::block_numbers, BSL_Data_Deinit(), BSL_FREE, and BSL_PrimaryBlock_t::encoded.

Referenced by BSL_API_QuerySecurity(), BSLP_PolicyRule_EvaluateAsSecOper(), and BSLP_QueryPolicy().

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ BSL_TLM_COUNTERS_ZERO

Enumeration Type Documentation

◆ BSL_BundleCRCType_e

◆ BSL_PolicyLocation_e

◆ BSL_ReasonCode_t

◆ BSL_SecOper_ConclusionState_e

◆ BSL_TlmCounterIndex_e

Function Documentation

◆ BSL_API_ApplySecurity()

◆ BSL_API_DeinitLib()

◆ BSL_API_InitLib()

◆ BSL_API_QuerySecurity()

◆ BSL_API_RegisterPolicyProvider()

◆ BSL_API_RegisterSecurityContext()

◆ BSL_HostDescriptors_Clear()

◆ BSL_HostDescriptors_Get()

◆ BSL_HostDescriptors_Set()

◆ BSL_LibCtx_AccumulateTlmCounters()

◆ BSL_PrimaryBlock_deinit()