BPSecLib_Private.h File Reference

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

#include <assert.h>
#include <inttypes.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <string.h>
#include <syslog.h>
#include <time.h>
#include <sys/types.h>
#include <qcbor/UsefulBuf.h>
#include "BPSecLib_Public.h"

Include dependency graph for BPSecLib_Private.h:

Data Structures
struct	BSL_Data_t
	Heap data storage and views. More...
struct	BSL_BundleTimestamp_t
	Creation Timestamp Defined in Section 4.2.7 of RFC 9171 [6]. More...
struct	BSL_PolicyDesc_t
	Descriptor of opaque data and callbacks for Policy Provider. More...
struct	BSL_SecCtxDesc_t
	Security Context descriptor (interface) More...

Macros
#define	_U_
	Mark an unused parameter Within a function definition.
#define	UNLIKELY(expr)   (expr)
	Hint to the compiler that the expression is expected to evaluate to false and the associated branch is unlikely.
#define	LIKELY(expr)   (expr)
	Hint to the compiler that the expression is expected to evaluate to true and the associated branch is likely.
#define	CHKRET(cond, val)
	Check a condition and if not met return a specific value.
#define	CHKVOID(cond)   CHKRET(cond, )
	Return from void functions if condition fails.
#define	CHKNULL(cond)   CHKRET(cond, NULL)
	Return a null pointer if condition fails.
#define	CHKFALSE(cond)   CHKRET(cond, false)
	Return false if condition fails.
#define	CHKERR1(cond)   CHKRET(cond, 1)
	Return the error value 1 if condition fails.
#define	CHKERRVAL(value)   CHKRET(!(value), (value))
	Check a value for non-zero and return that value.
#define	BSL_LOG_CRIT(...)   BSL_LogEvent(LOG_CRIT, __FILE__, __LINE__, __func__, __VA_ARGS__)
	Perform LOG_CRIT level logging with auto-filled parameters.
#define	BSL_LOG_ERR(...)   BSL_LogEvent(LOG_ERR, __FILE__, __LINE__, __func__, __VA_ARGS__)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
#define	BSL_LOG_WARNING(...)   BSL_LogEvent(LOG_WARNING, __FILE__, __LINE__, __func__, __VA_ARGS__)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
#define	BSL_LOG_INFO(...)   BSL_LogEvent(LOG_INFO, __FILE__, __LINE__, __func__, __VA_ARGS__)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
#define	BSL_LOG_DEBUG(...)   BSL_LogEvent(LOG_DEBUG, __FILE__, __LINE__, __func__, __VA_ARGS__)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
#define	CHK_TEMPL(expr, msg, return_code)
	Helpful macros for expressing invariants, pre/post conditions, and arg validation.
#define	CHK_AS_BOOL(expr)   CHK_TEMPL(expr, "Failed Property Check: Failed to satisfy", BSL_ERR_ARG_INVALID)
#define	CHK_ARG_EXPR(expr)    CHK_TEMPL(expr, "Illegal Argument: Argument expression check failed to satisfy", BSL_ERR_ARG_INVALID)
#define	CHK_ARG_NONNULL(var)    CHK_TEMPL((var) != NULL, "Illegal Argument: Argument null check failed to satisfy", BSL_ERR_ARG_NULL)
#define	CHK_PRECONDITION(expr)   CHK_TEMPL(expr, "Precondition Failed: Did not satisfy", BSL_ERR_FAILURE);
#define	CHK_PROPERTY(expr)   CHK_TEMPL(expr, "Property Failed: Did not satisfy", BSL_ERR_FAILURE);
#define	CHK_POSTCONDITION(expr)   CHK_TEMPL(expr, "Postcondition Failed: Did not satisfy", BSL_ERR_FAILURE);
#define	ASSERT_TEMPL(expr, msg)
#define	ASSERT_ARG_EXPR(expr)   ASSERT_TEMPL(expr, "Panic: Argument expression check failed to satisfy")
#define	ASSERT_ARG_NONNULL(var)   ASSERT_TEMPL((var) != NULL, "Panic: Null Argument check failed to satisfy")
#define	ASSERT_PROPERTY(expr)   ASSERT_TEMPL(expr, "Panic: Property check failed to satisfy")
#define	ASSERT_PRECONDITION(expr)   ASSERT_TEMPL(expr, "Panic: Precondition failed to satisfy")
#define	ASSERT_POSTCONDITION(expr)   ASSERT_TEMPL(expr, "Panic: Precondition failed to satisfy")
#define	BSL_DATA_INIT_NULL
	Static initializer for a data store.
#define	BSL_HOSTEID_INIT_INVALID
	Static initializer for an invalid BSL_HostEID_t.
#define	BSL_HOSTEID_INIT_INVALID
	Static initializer for an invalid BSL_HostEID_t.
#define	BSL_DEFAULT_BYTESTR_LEN   (128)
#define	BSL_SECROLE_ISVALID(role_value)   (((role_value) >= BSL_SECROLE_SOURCE) && ((role_value) <= BSL_SECROLE_ACCEPTOR))
#define	BSL_SecBlockType_IsSecBlock(block_id)    (((block_id) >= BSL_SECBLOCKTYPE_BIB) && ((block_id) <= BSL_SECBLOCKTYPE_BCB))
	Helper to determine if a given block type is security.

Typedefs
typedef uint8_t *	BSL_DataPtr_t
	Data pointer for BSL_Data_t.
typedef const uint8_t *	BSL_DataConstPtr_t
	Pointer to constant data for BSL_Data_t.
typedef int(*	BSL_PolicyInspect_f) (const void *user_data, BSL_SecurityActionSet_t *output_action_set, const BSL_BundleRef_t *bundle, BSL_PolicyLocation_e location)
	Callback interface to query policy provider to populate the action set.
typedef int(*	BSL_PolicyFinalize_f) (const void *user_data, const BSL_SecurityActionSet_t *output_action_set, const BSL_BundleRef_t *bundle, const BSL_SecurityResponseSet_t *response_output)
	Callback interface to query policy provider to populate the action set.
typedef void(*	BSL_PolicyDeinit_f) (void *user_data)
	Callback interface for policy provider to shut down and release any resources.
typedef bool(*	BSL_SecCtx_Validate_f) (BSL_LibCtx_t *lib, const BSL_BundleRef_t *bundle, const BSL_SecOper_t *sec_oper)
	Signature for Security Context validator for a sec OP.
typedef int(*	BSL_SecCtx_Execute_f) (BSL_LibCtx_t *lib, const BSL_BundleRef_t *bundle, const BSL_SecOper_t *sec_oper, BSL_SecOutcome_t *sec_outcome)
	Signature for Security Context executor for a sec OP.

Enumerations
enum	BSL_ErrCodes_e {   BSL_SUCCESS = 0 , BSL_ERR_FAILURE = -1 , BSL_ERR_ARG_NULL = -2 , BSL_ERR_ARG_INVALID = -3 ,   BSL_ERR_PROPERTY_CHECK_FAILED = -4 , BSL_ERR_INSUFFICIENT_SPACE = -5 , BSL_ERR_NOT_IMPLEMENTED = -6 , BSL_ERR_ENCODING = -7 ,   BSL_ERR_DECODING = -8 , BSL_ERR_NOT_FOUND = -9 , BSL_ERR_BUNDLE_OPERATION_FAILED = -10 , BSL_ERR_SECURITY_OPERATION_FAILED = -11 ,   BSL_ERR_HOST_CALLBACK_FAILED = -12 , BSL_ERR_POLICY_FAILED = -100 , BSL_ERR_SECURITY_CONTEXT_FAILED = -200 , BSL_ERR_SECURITY_CONTEXT_PARTIAL_FAIL = -201 ,   BSL_ERR_SECURITY_CONTEXT_VALIDATION_FAILED = -202 , BSL_ERR_SECURITY_CONTEXT_AUTH_FAILED = -203 , BSL_ERR_SECURITY_CONTEXT_CRYPTO_FAILED = -204 }
	Catalog of error code. More...
enum	BSL_PolicyAction_e { BSL_POLICYACTION_UNDEFINED = 0 , BSL_POLICYACTION_NOTHING , BSL_POLICYACTION_DROP_BLOCK , BSL_POLICYACTION_DROP_BUNDLE }
	Codes indicating the fate of a block if a security operation over it fails. More...
enum	BSL_BundleBlockTypeCode_e {   BSL_BLOCK_TYPE_PRIMARY = 0 , BSL_BLOCK_TYPE_PAYLOAD = 1 , BSL_BLOCK_TYPE_BUNDLE_AUTH = 2 , BSL_BLOCK_TYPE_PAYLOAD_INTEGRITY = 3 ,   BSL_BLOCK_TYPE_PAYLOAD_CONFIDENTIALITY = 4 , BSL_BLOCK_TYPE_PREVIOUS_HOP_INSERTION = 5 , BSL_BLOCK_TYPE_PREVIOUS_NODE = 6 , BSL_BLOCK_TYPE_BUNDLE_AGE = 7 ,   BSL_BLOCK_TYPE_METADATA_EXT = 8 , BSL_BLOCK_TYPE_EXT_SECURITY = 9 , BSL_BLOCK_TYPE_HOP_COUNT = 10 , BSL_BLOCK_TYPE_BIB = 11 ,   BSL_BLOCK_TYPE_BCB = 12 }
	Block types using IANA-assigned code points from [7]. More...
enum	BSL_BundleASBFlag_e { BSL_ASB_FLAG_PARAMS = 1 }
	Flags of the Abstract Security Block [3]. More...
enum	BSL_BundleCtrlFlag_e { BSL_BUNDLE_IS_FRAGMENT = 0x0001 }
	Bundle processing control flags. More...
enum	BSL_SecRole_e { BSL_SECROLE_SOURCE = 1000 , BSL_SECROLE_VERIFIER , BSL_SECROLE_ACCEPTOR }
	Security role of an operation. More...
enum	BSL_SecBlockType_e { BSL_SECBLOCKTYPE_BIB = 11 , BSL_SECBLOCKTYPE_BCB = 12 }
	RFC 9172-specified block type codes for BIB and BCB. More...
enum	BSL_SecParam_Types_e { BSL_SECPARAM_TYPE_UNKNOWN = 0 , BSL_SECPARAM_TYPE_INT64 , BSL_SECPARAM_TYPE_BYTESTR , BSL_SECPARAM_TYPE_STR }
	Security parameters defined in RFC9172 may be unsigned integers or bytestrings. More...
enum	BSL_SecParam_InternalIds {   BSL_SECPARAM_TYPE_INT_STARTINDEX = 1000 , BSL_SECPARAM_TYPE_KEY_ID , BSL_SECPARAM_TYPE_INT_FIXED_KEY , BSL_SECPARAM_TYPE_INT_USE_WRAPPED_KEY ,   BSL_SECPARAM_TYPE_AUTH_TAG , BSL_SECPARAM_TYPE_IV , BSL_SECPARAM_TYPE_INT_ENDINDEX }
	Defines supplementary Security Parameter type used internally by this implementation for testing or additional policy provider information. More...

Functions
uint8_t *	BSL_Log_DumpAsHexString (uint8_t *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.
void	BSL_openlog (void)
	Opens the event log.
void	BSL_closelog (void)
	Closes the event log.
int	BSL_LogGetSeverity (int *severity, const char *name)
	Interpret a text name as a severity level.
void	BSL_LogSetLeastSeverity (int severity)
	Set the least severity enabled for logging.
bool	BSL_LogIsEnabledFor (int severity)
	Determine if a particular severity is being logged.
void	BSL_LogEvent (int severity, const char *filename, int lineno, const char *funcname, const char *format,...)
	Log an event.
size_t	BSL_LibCtx_Sizeof (void)
	Return size of library context.
int	BSL_Data_Init (BSL_Data_t *data)
	Initialize an empty data struct.
int	BSL_Data_InitBuffer (BSL_Data_t *data, size_t bytelen)
	Initialize with an owned buffer of size bytelen.
int	BSL_Data_InitView (BSL_Data_t *data, size_t len, BSL_DataPtr_t src)
	Initialize a data struct as an overlay on optional external data.
void	BSL_Data_InitMove (BSL_Data_t *data, BSL_Data_t *src)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
int	BSL_Data_Deinit (BSL_Data_t *data)
	De-initialize a data struct, freeing if necessary.
int	BSL_Data_Resize (BSL_Data_t *data, size_t len)
	Resize the data, copying if necessary.
int	BSL_Data_CopyFrom (BSL_Data_t *data, size_t len, BSL_DataConstPtr_t src)
	Set an initialized data struct to a given size.
int	BSL_Data_AppendFrom (BSL_Data_t *data, size_t len, BSL_DataConstPtr_t src)
	Append an initialized data struct with a given size.
int	BSL_SeqReader_Deinit (BSL_SeqReader_t *obj)
	Release resources from a sequential reader.
int	BSL_SeqReader_Get (BSL_SeqReader_t *obj, uint8_t *buf, size_t *bufsize)
	Iterate a sequential reader.
int	BSL_SeqWriter_Deinit (BSL_SeqWriter_t *obj)
	Release resources from a sequential writer.
int	BSL_SeqWriter_Put (BSL_SeqWriter_t *obj, const uint8_t *buf, size_t *bufsize)
	Iterate a sequential writer.
int	BSL_HostEID_Init (BSL_HostEID_t *eid)
	Initialize an abstract EID.
void	BSL_HostEID_Deinit (BSL_HostEID_t *eid)
	De-initialize an abstract EID.
int	BSL_Host_GetSecSrcEID (BSL_HostEID_t *eid)
	Get the local EID used when this node is a security source.
int	BSL_HostEID_DecodeFromText (BSL_HostEID_t *eid, const char *text)
	Decode an EID from its text form.
int	BSL_HostEID_DecodeFromCBOR (BSL_HostEID_t *eid, void *decoder)
	Load an EID from CBOR.
int	BSL_HostEIDPattern_Init (BSL_HostEIDPattern_t *pat)
	Initialize an abstract EID Pattern.
void	BSL_HostEIDPattern_Deinit (BSL_HostEIDPattern_t *pat)
	De-initialize an abstract EID Pattern.
int	BSL_HostEID_EncodeToCBOR (const BSL_HostEID_t *eid, void *user_data)
	Encode a EID into a CBOR sequence.
int	BSL_HostEIDPattern_DecodeFromText (BSL_HostEIDPattern_t *pat, const char *text)
	Decode an EID Pattern from its text form.
bool	BSL_HostEIDPattern_IsMatch (const BSL_HostEIDPattern_t *pat, const BSL_HostEID_t *eid)
	Determine if an EID Pattern matches a specific EID.
int	BSL_BundleCtx_GetBundleMetadata (const BSL_BundleRef_t *bundle, BSL_PrimaryBlock_t *result_primary_block)
	Calls the host interface to get a bundle primary block information.abort.
int	BSL_BundleCtx_GetBlockIds (const BSL_BundleRef_t *bundle, size_t array_count, uint64_t *block_ids_array, size_t *result_count)
	Returns an array in which each element contains the id of the corresponding block.abort.
int	BSL_BundleCtx_GetBlockMetadata (const BSL_BundleRef_t *bundle, uint64_t block_num, BSL_CanonicalBlock_t *result_block)
	Returns information about the bundle Canonical block.
int	BSL_BundleCtx_CreateBlock (BSL_BundleRef_t *bundle, uint64_t block_type_code, uint64_t *block_num)
	Request the creation of a new block of a given type in the bundle.
int	BSL_BundleCtx_RemoveBlock (BSL_BundleRef_t *bundle, uint64_t block_num)
	Requests the removal of a block from a bundle.
int	BSL_BundleCtx_DeleteBundle (BSL_BundleRef_t *bundle)
	Requests dropping of bundle.
int	BSL_BundleCtx_ReallocBTSD (BSL_BundleRef_t *bundle, uint64_t block_num, size_t bytesize)
	Requests the re-allocation of a block's BTSD, useful for BCB.
int	BSL_SecResult_Init (BSL_SecResult_t *self, uint64_t result_id, uint64_t context_id, uint64_t target_block_num, BSL_Data_t content)
	Populate a pre-allocated result.
bool	BSL_SecResult_IsConsistent (const BSL_SecResult_t *self)
	Return true when internal invariant checks pass.
size_t	BSL_SecResult_Sizeof (void)
	Returns size in bytes of BSL_SecResult_s.
uint64_t	BSL_SecParam_GetId (const BSL_SecParam_t *self)
	Get parameter ID of this param.
bool	BSL_SecParam_IsConsistent (const BSL_SecParam_t *self)
	Return true if invariant conditions pass.
bool	BSL_SecParam_IsParamIDOutput (uint64_t param_id)
	Indicates true when this parameter is NOT an implementation-specific security parameter.
size_t	BSL_SecParam_Sizeof (void)
	Return size of BSL_SecParam_s struct type.
int	BSL_SecParam_InitBytestr (BSL_SecParam_t *self, uint64_t param_id, BSL_Data_t value)
	Initialize as a parameter containing a bytestring.
int	BSL_SecParam_InitInt64 (BSL_SecParam_t *self, uint64_t param_id, uint64_t value)
	Initialize as a parameter containing an integer as a value.
int	BSL_SecParam_InitStr (BSL_SecParam_t *self, uint64_t param_id, const char *value)
int	BSL_SecParam_IsInt64 (const BSL_SecParam_t *self)
	Returns true when the value type is an integer.
uint64_t	BSL_SecParam_GetAsUInt64 (const BSL_SecParam_t *self)
	Retrieve integer value of result when this result type is integer.
int	BSL_SecParam_GetAsBytestr (const BSL_SecParam_t *self, BSL_Data_t *result)
	Retrieve bytestring value of result when security parameter type is bytestring.
size_t	BSL_SecOper_Sizeof (void)
void	BSL_SecOper_Init (BSL_SecOper_t *self)
	Initialize a newly allocated structure.
void	BSL_SecOper_InitSet (BSL_SecOper_t *self, const BSL_SecOper_t *src)
	Initialize from a copy.
void	BSL_SecOper_Deinit (BSL_SecOper_t *self)
	Empty and release any resources used internally by this structure.
void	BSL_SecOper_Set (BSL_SecOper_t *self, const BSL_SecOper_t *src)
	Set from a copy.
void	BSL_SecOper_Populate (BSL_SecOper_t *self, uint64_t context_id, uint64_t target_block_num, uint64_t sec_block_num, BSL_SecBlockType_e sec_type, BSL_SecRole_e sec_role, BSL_PolicyAction_e failure_code)
	Populate an initialized Security Operation with the given values.
bool	BSL_SecOper_IsConsistent (const BSL_SecOper_t *self)
	Returns true if internal consistency and sanity checks pass.
const BSL_SecParam_t *	BSL_SecOper_GetParamAt (const BSL_SecOper_t *self, size_t index)
	Returns a pointer to the Security Parameter at a given index in the list of all parameters.
uint64_t	BSL_SecOper_GetSecurityBlockNum (const BSL_SecOper_t *self)
	Get the block number of the security block containing this sec operation.
uint64_t	BSL_SecOper_GetTargetBlockNum (const BSL_SecOper_t *self)
	Get the block number of the target block covered by this security operation.
size_t	BSL_SecOper_CountParams (const BSL_SecOper_t *self)
	Get the count of parameters contained within this security operation.
void	BSL_SecOper_AppendParam (BSL_SecOper_t *self, const BSL_SecParam_t *param)
	Add the given security parameter to this list of parameters.
bool	BSL_SecOper_IsRoleSource (const BSL_SecOper_t *self)
	Return true if this security operation's role is SOURCE.
bool	BSL_SecOper_IsRoleVerifier (const BSL_SecOper_t *self)
	Return true if this security operation's role is Verifier.
bool	BSL_SecOper_IsRoleAcceptor (const BSL_SecOper_t *self)
	Return true if this security operation's role is Acceptor.
bool	BSL_SecOper_IsBIB (const BSL_SecOper_t *self)
	Return true if this security operation is BIB.
BSL_SecOper_ConclusionState_e	BSL_SecOper_GetConclusion (const BSL_SecOper_t *self)
	Retrieve the conclusion state of a security operation.
void	BSL_SecOper_SetConclusion (BSL_SecOper_t *self, BSL_SecOper_ConclusionState_e new_conclusion)
	Set the security operation conclusion state.
size_t	BSL_AbsSecBlock_Sizeof (void)
	Returns the size of the ::BSL_AbsSecBlock_t struct in bytes.
void	BSL_AbsSecBlock_Init (BSL_AbsSecBlock_t *self, int64_t sec_context_id, BSL_HostEID_t source_eid)
	Populate a pre-allocated Abstract Security Block.
bool	BSL_AbsSecBlock_IsConsistent (const BSL_AbsSecBlock_t *self)
	Checks internal consistency and sanity of this structure.
void	BSL_AbsSecBlock_InitEmpty (BSL_AbsSecBlock_t *self)
	Initialize a pre-allocated ASB with no contents.
void	BSL_AbsSecBlock_Deinit (BSL_AbsSecBlock_t *self)
	Deinitializes and clears this ASB, clearing and releasing any owned memory.
void	BSL_AbsSecBlock_Print (const BSL_AbsSecBlock_t *self)
	Prints to LOG INFO.
bool	BSL_AbsSecBlock_IsEmpty (const BSL_AbsSecBlock_t *self)
	Returns true if this ASB contains nothing (i.e., no targets, params and results)
bool	BSL_AbsSecBlock_ContainsTarget (const BSL_AbsSecBlock_t *self, uint64_t target_block_num)
	Returns true if a given ASB contains the given block number as a security target.
void	BSL_AbsSecBlock_AddTarget (BSL_AbsSecBlock_t *self, uint64_t target_block_id)
	Adds a given block ID as a security target covered by this ASB.
void	BSL_AbsSecBlock_AddParam (BSL_AbsSecBlock_t *self, const BSL_SecParam_t *param)
	Add a security parameter to this security block (does NOT copy)
void	BSL_AbsSecBlock_AddResult (BSL_AbsSecBlock_t *self, const BSL_SecResult_t *result)
	Add a security result to this security block (does NOT copy)
int	BSL_AbsSecBlock_StripResults (BSL_AbsSecBlock_t *self, uint64_t target_block_num)
	Remove security parameters and results found in outcome from this ASB.
ssize_t	BSL_AbsSecBlock_EncodeToCBOR (const BSL_AbsSecBlock_t *self, UsefulBuf buf)
	Encodes this ASB into a CBOR string into the space pre-allocated indicated by the argument.
int	BSL_AbsSecBlock_DecodeFromCBOR (BSL_AbsSecBlock_t *self, const BSL_Data_t *encoded_cbor)
	Decodes and populates this ASB from a CBOR string.
size_t	BSL_SecOutcome_Sizeof (void)
	Returns the size of the BSL_SecOutcome_s structure.
void	BSL_SecOutcome_Init (BSL_SecOutcome_t *self, const BSL_SecOper_t *sec_oper, size_t allocation_size)
	Populate a pre-allocated security outcome struct.
void	BSL_SecOutcome_Deinit (BSL_SecOutcome_t *self)
	Release any resources owned by this security outcome.
bool	BSL_SecOutcome_IsConsistent (const BSL_SecOutcome_t *self)
	Return true if internal invariants hold.
void	BSL_SecOutcome_AppendResult (BSL_SecOutcome_t *self, const BSL_SecResult_t *sec_result)
	Append a Security Result to this outcome.
const BSL_SecResult_t *	BSL_SecOutcome_GetResultAtIndex (const BSL_SecOutcome_t *self, size_t index)
	Get the result at index i.
size_t	BSL_SecOutcome_CountResults (const BSL_SecOutcome_t *self)
	Get the number of results.
void	BSL_SecOutcome_AppendParam (BSL_SecOutcome_t *self, const BSL_SecParam_t *param)
	Append a Security Parameter to this outcome.
size_t	BSL_SecOutcome_CountParams (const BSL_SecOutcome_t *self)
	Returns number of parameters in this outcome.
const BSL_SecParam_t *	BSL_SecOutcome_GetParamAt (const BSL_SecOutcome_t *self, size_t index)
	Get the security parameter from the security outcome at the provided index.
bool	BSL_SecOutcome_IsInAbsSecBlock (const BSL_SecOutcome_t *self, const BSL_AbsSecBlock_t *abs_sec_block)
	Returns true if this (the parameters and results) is contained within the given ASK.
size_t	BSL_SecurityAction_Sizeof (void)
bool	BSL_SecurityAction_IsConsistent (const BSL_SecurityAction_t *self)
void	BSL_SecurityAction_Init (BSL_SecurityAction_t *self)
	Initialize security action.
void	BSL_SecurityAction_InitSet (BSL_SecurityAction_t *self, const BSL_SecurityAction_t *src)
	Initialize from a copy.
void	BSL_SecurityAction_Deinit (BSL_SecurityAction_t *self)
	De-initialize security action.
int	BSL_SecurityAction_AppendSecOper (BSL_SecurityAction_t *self, BSL_SecOper_t *sec_oper)
	Add security operation to security action, with deterministic ordering.
int	BSL_SecurityAction_OrderSecOps (BSL_SecurityAction_t *self)
	Order the Security operations such that execution will be successful.
size_t	BSL_SecurityAction_CountSecOpers (const BSL_SecurityAction_t *self)
BSL_SecOper_t *	BSL_SecurityAction_GetSecOperAtIndex (const BSL_SecurityAction_t *self, size_t index)
void	BSL_SecurityAction_IncrError (BSL_SecurityAction_t *self)
	Increment a security failure for this action set.
size_t	BSL_SecurityAction_CountErrors (const BSL_SecurityAction_t *self)
	Returns count of failures after processing this action.
size_t	BSL_SecurityActionSet_Sizeof (void)
	Returns size of the struct, helpful for dynamic allocation.
void	BSL_SecurityActionSet_Init (BSL_SecurityActionSet_t *self)
	Initialize a new security action set.
void	BSL_SecurityActionSet_Deinit (BSL_SecurityActionSet_t *self)
	Zeroize, clear, and release itself and any owned resources.
int	BSL_SecurityActionSet_AppendAction (BSL_SecurityActionSet_t *self, const BSL_SecurityAction_t *action)
	Append a security operation to the security action set.
bool	BSL_SecurityActionSet_IsConsistent (const BSL_SecurityActionSet_t *self)
	Return true if internal sanity and consistency checks pass.
size_t	BSL_SecurityActionSet_CountOperations (const BSL_SecurityActionSet_t *self)
size_t	BSL_SecurityActionSet_CountActions (const BSL_SecurityActionSet_t *self)
	Count number of security operations present in this policy action set.
const BSL_SecurityAction_t *	BSL_SecurityActionSet_GetActionAtIndex (const BSL_SecurityActionSet_t *self, size_t index)
	Returns the Security Operation at the given index.
size_t	BSL_SecurityActionSet_CountErrors (const BSL_SecurityActionSet_t *self)
	Returns count of failures after processing this action set.
size_t	BSL_SecurityResponseSet_Sizeof (void)
	Returns size of this struct type.
void	BSL_SecurityResponseSet_Init (BSL_SecurityResponseSet_t *self, size_t noperations, size_t nfailed)
	Initialize with the given count of operations and failures.
void	BSL_SecurityResponseSet_Deinit (BSL_SecurityResponseSet_t *self)
	Zeroize itself and release any owned resources.
bool	BSL_SecurityResponseSet_IsConsistent (const BSL_SecurityResponseSet_t *self)
	Return true if internal consistency checks pass.
size_t	BSL_SecurityResponseSet_CountResponses (const BSL_SecurityResponseSet_t *self)
	Return number of responses (operations acted upon)
int	BSL_PolicyRegistry_InspectActions (const BSL_LibCtx_t *bsl, BSL_SecurityActionSet_t *output_action_set, const BSL_BundleRef_t *bundle, BSL_PolicyLocation_e location)
	Queries the policy provider for any security operations to take on the bundle.
int	BSL_PolicyRegistry_FinalizeActions (const BSL_LibCtx_t *bsl, const BSL_SecurityActionSet_t *policy_actions, const BSL_BundleRef_t *bundle, const BSL_SecurityResponseSet_t *response_output)
	Finalizes policy provider for sec ops & sec results for a bundle.
int	BSL_SecCtx_ExecutePolicyActionSet (BSL_LibCtx_t *lib, BSL_SecurityResponseSet_t *output_response, BSL_BundleRef_t *bundle, const BSL_SecurityActionSet_t *action_set)
	Call the underlying security context to perform the given action.
bool	BSL_SecCtx_ValidatePolicyActionSet (BSL_LibCtx_t *lib, const BSL_BundleRef_t *bundle, const BSL_SecurityActionSet_t *action_set)

Detailed Description

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

This file is for backend and BSL-adjacent modules (the Policy Provider, Security Context, and Test Harness) to have more reach into the BSL, without requiring any of them to have specific dependencies on the other. The Host BPA should only need the purely public header file.

Author

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

Macro Definition Documentation

_U_

#define _U_

Mark an unused parameter Within a function definition.

This avoids compiler warnings when parameters need to be present to satisfy an interface but are otherwise unused.

For example, this second parameter is marked unused:

void myfunc(int param, int unused _U_)

ASSERT_TEMPL

#define ASSERT_TEMPL	(		expr,
			msg
	)

Value:

    do                                          \
    {                                           \
        if (!(expr))                            \
        {                                       \
            BSL_LOG_ERR("" msg " (" #expr ")"); \
            assert(!(expr));                    \
        }                                       \
    }                                           \
    while (0)

BSL_DATA_INIT_NULL

#define BSL_DATA_INIT_NULL

Value:

    {                                         \
        .owned = false, .ptr = NULL, .len = 0 \
    }

Static initializer for a data store.

See also

BSL_Data_Init()

BSL_HOSTEID_INIT_INVALID [1/2]

#define BSL_HOSTEID_INIT_INVALID

Value:

    {                            \
        .handle = NULL           \
    }

Static initializer for an invalid BSL_HostEID_t.

Opaque pointer to BPA-specific Endpoint ID Pattern storage.

Even after this, BSL_HostEID_Init() must be used to get into a valid state.

Ownership of the object is kept by the BPA, and these are only references. Static initializer for an invalid BSL_HostEIDPattern_t. Even after this, BSL_HostEIDPattern_Init() must be used to get into a valid state.

BSL_HOSTEID_INIT_INVALID [2/2]

#define BSL_HOSTEID_INIT_INVALID

Value:

    {                            \
        .handle = NULL           \
    }

Static initializer for an invalid BSL_HostEID_t.

Opaque pointer to BPA-specific Endpoint ID Pattern storage.

Even after this, BSL_HostEID_Init() must be used to get into a valid state.

Ownership of the object is kept by the BPA, and these are only references. Static initializer for an invalid BSL_HostEIDPattern_t. Even after this, BSL_HostEIDPattern_Init() must be used to get into a valid state.

BSL_LOG_CRIT

#define BSL_LOG_CRIT

(

...

)

BSL_LogEvent(LOG_CRIT, __FILE__, __LINE__, __func__, __VA_ARGS__)

Perform LOG_CRIT level logging with auto-filled parameters.

The arguments to this macro are passed to BSL_LogEvent() as the format and its parameter values.

CHK_TEMPL

#define CHK_TEMPL	(		expr,
			msg,
			return_code
	)

Value:

    do                                                                         \
    {                                                                          \
        if (!(expr))                                                           \
        {                                                                      \
            BSL_LOG_ERR("" msg " (" #expr ") ... [errcode=" #return_code "]"); \
            assert(!(expr));                                                   \
            return return_code;                                                \
        }                                                                      \
    }                                                                          \
    while (0)

Helpful macros for expressing invariants, pre/post conditions, and arg validation.

CHKERRVAL

#define CHKERRVAL

(

value

)

CHKRET(!(value), (value))

Check a value for non-zero and return that value.

Warning

The parameter is evaluated twice so should be a simple variable.

Parameters

value

The value to check and conditionally return.

CHKRET

#define CHKRET	(		cond,
			val
	)

Value:

    if (!LIKELY(cond))    \
    {                     \
        return val;       \
    }

Check a condition and if not met return a specific value.

Parameters

cond	The condition to check.
val	The return value if the check fails.

Deprecated:

LIKELY

#define LIKELY

(

expr

)

(expr)

Hint to the compiler that the expression is expected to evaluate to true and the associated branch is likely.

Parameters

expr	The expression to evaluate.

Returns

The boolean evaluation of the expression.

UNLIKELY

#define UNLIKELY

(

expr

)

(expr)

Hint to the compiler that the expression is expected to evaluate to false and the associated branch is unlikely.

Parameters

expr	The expression to evaluate.

Returns

The boolean evaluation of the expression.

Typedef Documentation

BSL_SecCtx_Execute_f

typedef int(* BSL_SecCtx_Execute_f) (BSL_LibCtx_t *lib, const BSL_BundleRef_t *bundle, const BSL_SecOper_t *sec_oper, BSL_SecOutcome_t *sec_outcome)

Signature for Security Context executor for a sec OP.

Parameters

[in]	lib	The library context.
[in,out]	bundle	The bundle to modify.
[in]	sec_oper	The security operation to perform.
[in,out]	sec_outcome	The pre-allocated outcome to populate

Returns

0 if security operation performed successfully.

BSL_SecCtx_Validate_f

typedef bool(* BSL_SecCtx_Validate_f) (BSL_LibCtx_t *lib, const BSL_BundleRef_t *bundle, const BSL_SecOper_t *sec_oper)

Signature for Security Context validator for a sec OP.

Parameters

[in]	lib	The library context.
[in]	bundle	The bundle to inspect.
[in]	sec_oper	The security operation to perform.

Returns

True if security operation is deemed valid.

Enumeration Type Documentation

BSL_BundleASBFlag_e

enum BSL_BundleASBFlag_e

Flags of the Abstract Security Block [3].

Enumerator
BSL_ASB_FLAG_PARAMS	Flag set when parameters are present.

BSL_BundleBlockTypeCode_e

enum BSL_BundleBlockTypeCode_e

Block types using IANA-assigned code points from [7].

Enumerator
BSL_BLOCK_TYPE_PRIMARY	Primary block ID (a special case)
BSL_BLOCK_TYPE_PAYLOAD	Payload block.
BSL_BLOCK_TYPE_BIB	Block Integrity [7].
BSL_BLOCK_TYPE_BCB	Block Confidentiality [7].

BSL_BundleCtrlFlag_e

enum BSL_BundleCtrlFlag_e

Bundle processing control flags.

Defined in Section 4.2.3 of RFC 9171 [6].

Enumerator
BSL_BUNDLE_IS_FRAGMENT	Set if this bundle is a fragment.

BSL_ErrCodes_e

enum BSL_ErrCodes_e

Catalog of error code.

Note

BSL error codes are negative, such that a caller can check if (BSL_MyFunc(...) < 0) for errors.

Enumerator
BSL_SUCCESS	Placeholder for non-error code.
BSL_ERR_FAILURE	Uncategorized failed (prefer to avoid)
BSL_ERR_ARG_NULL	Function pointer argument is NULL.
BSL_ERR_ARG_INVALID	Function argument does not satisfy a given predicate.
BSL_ERR_PROPERTY_CHECK_FAILED	The BSL of a structure within it is not in a valid state.
BSL_ERR_INSUFFICIENT_SPACE	Insufficient space to complete.
BSL_ERR_NOT_IMPLEMENTED	Requested functionality not yet implemented.
BSL_ERR_ENCODING	CBOR encoding failure.
BSL_ERR_DECODING	CBOR decoding failure.
BSL_ERR_NOT_FOUND	Requested value not found for key.
BSL_ERR_BUNDLE_OPERATION_FAILED	Bundle manipulation failed (add/remove or change BTSD)
BSL_ERR_SECURITY_OPERATION_FAILED	Security operation failed (e.g., BIB did not have enough parameters)
BSL_ERR_HOST_CALLBACK_FAILED	Callback to the host BPA returned a non-zero code.
BSL_ERR_POLICY_FAILED	Policy Errors start at 100. General error code for errors arising from a Policy Provider
BSL_ERR_SECURITY_CONTEXT_FAILED	Security Context errors start at 200. General error code for errors arising from a Security Context.
BSL_ERR_SECURITY_CONTEXT_PARTIAL_FAIL	General code where at least some security operations failed.
BSL_ERR_SECURITY_CONTEXT_VALIDATION_FAILED	Indicates security context validate failed.
BSL_ERR_SECURITY_CONTEXT_AUTH_FAILED	Indicates an HMAC Auth failed.
BSL_ERR_SECURITY_CONTEXT_CRYPTO_FAILED	Indicates a cryptographic operation failed (encrypt/decrypt)

BSL_PolicyAction_e

enum BSL_PolicyAction_e

Codes indicating the fate of a block if a security operation over it fails.

Enumerator
BSL_POLICYACTION_UNDEFINED	Placeholder for zero - should never occur.
BSL_POLICYACTION_NOTHING	Do nothing, keep the block even if it fails.
BSL_POLICYACTION_DROP_BLOCK	Drop on the target block.
BSL_POLICYACTION_DROP_BUNDLE	Drop the entire bundle.

BSL_SecBlockType_e

enum BSL_SecBlockType_e

RFC 9172-specified block type codes for BIB and BCB.

Todo:

Consider making an RFC9172 header file.

Enumerator
BSL_SECBLOCKTYPE_BIB	RFC9172 code for BIB.
BSL_SECBLOCKTYPE_BCB	RFC9172 code for BCB.

BSL_SecParam_InternalIds

enum BSL_SecParam_InternalIds

Defines supplementary Security Parameter type used internally by this implementation for testing or additional policy provider information.

Todo:

• Maybe move to SecurityContext.h

Enumerator
BSL_SECPARAM_TYPE_INT_STARTINDEX	Do not use. Indicates start index of internal param ids.
BSL_SECPARAM_TYPE_KEY_ID	Used to pass in a key id found in the key registry.
BSL_SECPARAM_TYPE_INT_FIXED_KEY	Used by tests to pass in a specific key bytestring.
BSL_SECPARAM_TYPE_INT_USE_WRAPPED_KEY	This must be explicitly set, and set to 0, to avoid generating a wrapped key.
BSL_SECPARAM_TYPE_INT_ENDINDEX	Do not use. Indicates final index of internal param ids.

BSL_SecParam_Types_e

enum BSL_SecParam_Types_e

Security parameters defined in RFC9172 may be unsigned integers or bytestrings.

Enumerator
BSL_SECPARAM_TYPE_UNKNOWN	Indicates parsed value not of expected type.
BSL_SECPARAM_TYPE_INT64	Indicates value type is an unsigned integer.
BSL_SECPARAM_TYPE_BYTESTR	Indicates the value type is a byte string.

BSL_SecRole_e

enum BSL_SecRole_e

Security role of an operation.

Enumerator
BSL_SECROLE_SOURCE	Source producing the security result.
BSL_SECROLE_VERIFIER	Only check the security result.
BSL_SECROLE_ACCEPTOR	Check and then remove the security result if correct.

Function Documentation

BSL_AbsSecBlock_AddParam()

void BSL_AbsSecBlock_AddParam	(	BSL_AbsSecBlock_t *	self,
		const BSL_SecParam_t *	param
	)

Add a security parameter to this security block (does NOT copy)

Todo:

• Can be backend-only.

Parameters

[in,out]	self	This security block
[in]	param	Non-Null Security parameter pointer to add to list

References BSL_AbsSecBlock_IsConsistent().

BSL_AbsSecBlock_AddResult()

void BSL_AbsSecBlock_AddResult	(	BSL_AbsSecBlock_t *	self,
		const BSL_SecResult_t *	result
	)

Add a security result to this security block (does NOT copy)

Todo:

• Can be backend-only.

Parameters

[in,out]	self	This security block
[in]	result	Non-Null Security result pointer to add to list

References BSL_AbsSecBlock_IsConsistent().

BSL_AbsSecBlock_AddTarget()

void BSL_AbsSecBlock_AddTarget	(	BSL_AbsSecBlock_t *	self,
		uint64_t	target_block_id
	)

Adds a given block ID as a security target covered by this ASB.

Todo:

• Can be backend-only.

Parameters

[in,out]	self	This ASB.
[in]	target_block_id	ID of a block, 0 indicates primary block as usual.

References BSL_AbsSecBlock_IsConsistent().

BSL_AbsSecBlock_ContainsTarget()

bool BSL_AbsSecBlock_ContainsTarget	(	const BSL_AbsSecBlock_t *	self,
		uint64_t	target_block_num
	)

Returns true if a given ASB contains the given block number as a security target.

Parameters

[in,out]	self	This ASB.
[in]	target_block_num	ID of a block, 0 indicates primary block

Returns

true if ASB contains target

References BSL_AbsSecBlock_IsConsistent().

Referenced by BSL_API_QuerySecurity().

BSL_AbsSecBlock_DecodeFromCBOR()

int BSL_AbsSecBlock_DecodeFromCBOR	(	BSL_AbsSecBlock_t *	self,
		const BSL_Data_t *	encoded_cbor
	)

Decodes and populates this ASB from a CBOR string.

Parameters

[in,out]	self	This allocated, but uninitialized ASB to populate.
[in]	encoded_cbor	A buffer containing a CBOR string representing the ASB

Returns

Negative on error

References BSL_AbsSecBlock_InitEmpty(), BSL_AbsSecBlock_IsConsistent(), BSL_Data_InitView(), BSL_ERR_DECODING, BSL_HostEID_DecodeFromCBOR(), BSL_HostEID_Init(), BSL_LOG_DEBUG, BSL_LOG_ERR, BSL_LOG_WARNING, BSL_SecParam_InitBytestr(), BSL_SecParam_InitInt64(), BSL_SecResult_Init(), BSL_SUCCESS, BSL_Data_t::len, BSL_Data_t::owned, and BSL_Data_t::ptr.

Referenced by BSL_API_QuerySecurity().

BSL_AbsSecBlock_Deinit()

void BSL_AbsSecBlock_Deinit

(

BSL_AbsSecBlock_t *

self

)

Deinitializes and clears this ASB, clearing and releasing any owned memory.

Parameters

[in,out]

self

This ASB

References BSL_AbsSecBlock_IsConsistent(), and BSL_HostEID_Deinit().

Referenced by BSL_API_QuerySecurity().

BSL_AbsSecBlock_EncodeToCBOR()

ssize_t BSL_AbsSecBlock_EncodeToCBOR	(	const BSL_AbsSecBlock_t *	self,
		UsefulBuf	buf
	)

Encodes this ASB into a CBOR string into the space pre-allocated indicated by the argument.

Parameters

[in]	self	This ASB.
[in]	buf	A buffer with allocated space for the encoded CBOR or the SizeCalculateUsefulBuf value to get the real size.

Returns

Integer contains number of bytes written to buffer, negative indicates error.

References BSL_AbsSecBlock_IsConsistent(), BSL_ERR_ENCODING, BSL_HostEID_EncodeToCBOR(), BSL_LOG_ERR, BSL_LOG_INFO, BSL_SecParam_GetAsBytestr(), BSL_SecParam_GetAsUInt64(), BSL_SecParam_IsInt64(), BSL_Data_t::len, and BSL_Data_t::ptr.

BSL_AbsSecBlock_Init()

void BSL_AbsSecBlock_Init	(	BSL_AbsSecBlock_t *	self,
		int64_t	sec_context_id,
		BSL_HostEID_t	source_eid
	)

Populate a pre-allocated Abstract Security Block.

Todo:

• Can be backend-only.

Parameters

[in,out]	self	This ASB
[in]	sec_context_id	Security Context ID
[in]	source_eid	Source EID in format native to host BPA.

References BSL_AbsSecBlock_IsConsistent().

BSL_AbsSecBlock_InitEmpty()

void BSL_AbsSecBlock_InitEmpty

(

BSL_AbsSecBlock_t *

self

)

Initialize a pre-allocated ASB with no contents.

Parameters

[in,out]

self

This ASB

Referenced by BSL_AbsSecBlock_DecodeFromCBOR().

BSL_AbsSecBlock_IsConsistent()

bool BSL_AbsSecBlock_IsConsistent

(

const BSL_AbsSecBlock_t *

self

)

Checks internal consistency and sanity of this structure.

Parameters

[in]

self

This ASB

Referenced by BSL_AbsSecBlock_AddParam(), BSL_AbsSecBlock_AddResult(), BSL_AbsSecBlock_AddTarget(), BSL_AbsSecBlock_ContainsTarget(), BSL_AbsSecBlock_DecodeFromCBOR(), BSL_AbsSecBlock_Deinit(), BSL_AbsSecBlock_EncodeToCBOR(), BSL_AbsSecBlock_Init(), BSL_AbsSecBlock_StripResults(), and BSL_SecOutcome_IsInAbsSecBlock().

BSL_AbsSecBlock_IsEmpty()

bool BSL_AbsSecBlock_IsEmpty

(

const BSL_AbsSecBlock_t *

self

)

Returns true if this ASB contains nothing (i.e., no targets, params and results)

Parameters

[in]

self

This ASB.

Returns

true if ASB is empty

BSL_AbsSecBlock_Print()

void BSL_AbsSecBlock_Print

(

const BSL_AbsSecBlock_t *

self

)

Prints to LOG INFO.

Todo:

• Can be backend-only.

Parameters

[in]

self

This ASB

Todo:

Refactor to dump this to a pre-allocated string.

References BSL_Log_DumpAsHexString(), and BSL_LOG_INFO.

BSL_AbsSecBlock_Sizeof()

size_t BSL_AbsSecBlock_Sizeof

(

void

)

Returns the size of the ::BSL_AbsSecBlock_t struct in bytes.

Returns

size of the struct

Referenced by BSL_API_QuerySecurity().

BSL_AbsSecBlock_StripResults()

int BSL_AbsSecBlock_StripResults	(	BSL_AbsSecBlock_t *	self,
		uint64_t	target_block_num
	)

Remove security parameters and results found in outcome from this ASB.

Todo:

• Can be backend-only.

Parameters

[in,out]	self	This ASB
[in]	outcome	Security Operation outcome containing params and results

Returns

Negative on error, otherwise count of things removed.

References BSL_AbsSecBlock_IsConsistent(), BSL_ERR_PROPERTY_CHECK_FAILED, and BSL_LOG_ERR.

BSL_BundleCtx_CreateBlock()

int BSL_BundleCtx_CreateBlock	(	BSL_BundleRef_t *	bundle,
		uint64_t	block_type_code,
		uint64_t *	block_num
	)

Request the creation of a new block of a given type in the bundle.

Parameters

[in]	bundle	Context bundle
[in]	block_type_code	The type of block to be created (e.g, 1 means payload)
[out]	block_num	Pointer to integer containing the number of the block just created.abort

Returns

0 on success, negative on error

References BSL_HostDescriptors_t::block_create_fn, BSL_ERR_HOST_CALLBACK_FAILED, and BSL_SUCCESS.

BSL_BundleCtx_DeleteBundle()

int BSL_BundleCtx_DeleteBundle

(

BSL_BundleRef_t *

bundle

)

Requests dropping of bundle.

Parameters

[in]

bundle

Context bundle

Returns

0 on success, negative on failure.

References BSL_ERR_HOST_CALLBACK_FAILED, BSL_SUCCESS, and BSL_HostDescriptors_t::bundle_delete_fn.

Referenced by BSL_API_ApplySecurity().

BSL_BundleCtx_GetBlockIds()

int BSL_BundleCtx_GetBlockIds	(	const BSL_BundleRef_t *	bundle,
		size_t	array_count,
		uint64_t *	block_ids_array,
		size_t *	result_count
	)

Returns an array in which each element contains the id of the corresponding block.abort.

Parameters

[in]	bundle	Bundle context
[in]	array_count	Number of elements in block_id_index_array
[out]	block_id_index_array	Array of array_count elements for results
[out]	result_count	Contains the number of elements put into the array

Returns

0 on success, negative on error

References BSL_ERR_HOST_CALLBACK_FAILED, BSL_SUCCESS, and BSL_HostDescriptors_t::bundle_get_block_ids.

Referenced by BSL_API_QuerySecurity().

BSL_BundleCtx_GetBlockMetadata()

int BSL_BundleCtx_GetBlockMetadata	(	const BSL_BundleRef_t *	bundle,
		uint64_t	block_num,
		BSL_CanonicalBlock_t *	result_block
	)

Returns information about the bundle Canonical block.

Parameters

[in]	bundle	Context bundle
[in]	block_num	The number of the bundle canonical block we seek information on
[out]	result_block	Pointer to allocated memory which contains the results of the query.

Returns

0 on success, negative on error

References BSL_HostDescriptors_t::block_metadata_fn, BSL_ERR_HOST_CALLBACK_FAILED, and BSL_SUCCESS.

Referenced by BSL_API_QuerySecurity(), test_RFC9173_AppendixA_Example2_BCB_Acceptor(), test_RFC9173_AppendixA_Example2_BCB_Source(), and test_SecurityContext_BIB_Source().

BSL_BundleCtx_GetBundleMetadata()

int BSL_BundleCtx_GetBundleMetadata	(	const BSL_BundleRef_t *	bundle,
		BSL_PrimaryBlock_t *	result_primary_block
	)

Calls the host interface to get a bundle primary block information.abort.

Parameters

[in]	bundle	Bundle context
[out]	result_primary_block	Non-null pointer to result which gets populated on a zero return code.

Returns

0 on success, negative on error

References BSL_ERR_HOST_CALLBACK_FAILED, BSL_SUCCESS, and BSL_HostDescriptors_t::bundle_metadata_fn.

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

BSL_BundleCtx_ReallocBTSD()

int BSL_BundleCtx_ReallocBTSD	(	BSL_BundleRef_t *	bundle,
		uint64_t	block_num,
		size_t	bytesize
	)

Requests the re-allocation of a block's BTSD, useful for BCB.

Note

Uses semantics similar to memcpy().

Parameters

[in]	bundle	Context bundle
[in]	block_num	Number of block requesting re-allocated of BTSD
[in]	bytesize	Size of new BTSD

Returns

0 on success, negative on failure.

References BSL_HostDescriptors_t::block_realloc_btsd_fn, BSL_HostDescriptors_t::block_remove_fn, BSL_ERR_HOST_CALLBACK_FAILED, and BSL_SUCCESS.

BSL_BundleCtx_RemoveBlock()

int BSL_BundleCtx_RemoveBlock	(	BSL_BundleRef_t *	bundle,
		uint64_t	block_num
	)

Requests the removal of a block from a bundle.

Parameters

[in]	bundle	Context bundle
[in]	block_num	Block number to be removed

Returns

0 on success, negative on failure.

References BSL_HostDescriptors_t::block_remove_fn, BSL_ERR_HOST_CALLBACK_FAILED, and BSL_SUCCESS.

Referenced by BSL_API_ApplySecurity().

BSL_closelog()

void BSL_closelog

(

void

)

Closes the event log.

This is a mimic to POSIX closelog()

See also

BSL_openlog

References event_queue, BSL_LogEvent_event_t::message, BSL_LogEvent_event_t::severity, thr_sink, and thr_valid.

BSL_Data_AppendFrom()

int BSL_Data_AppendFrom	(	BSL_Data_t *	data,
		size_t	len,
		BSL_DataConstPtr_t	src
	)

Append an initialized data struct with a given size.

Parameters

[in,out]	data	The data to copy into, which must not be NULL.
[in]	len	The total length to allocate, which may be non-zero.
[in]	src	An optional source buffer to copy from, from which len bytes will be copied.

Returns

Zero upon success.

References BSL_Data_Resize(), BSL_LOG_ERR, BSL_SUCCESS, BSL_Data_t::len, and BSL_Data_t::ptr.

BSL_Data_CopyFrom()

int BSL_Data_CopyFrom	(	BSL_Data_t *	data,
		size_t	len,
		BSL_DataConstPtr_t	src
	)

Set an initialized data struct to a given size.

Parameters

[in,out]	data	The data to copy into, which must not be NULL.
[in]	len	The total length to allocate, which may be non-zero.
[in]	src	An optional source buffer to copy from, from which len bytes will be copied.

Returns

Zero upon success.

References BSL_Data_Resize(), BSL_LOG_ERR, BSL_SUCCESS, BSL_Data_t::owned, and BSL_Data_t::ptr.

Referenced by BSL_Crypto_AddRegistryKey(), and bsl_mock_decode_eid().

BSL_Data_Deinit()

int BSL_Data_Deinit

(

BSL_Data_t *

data

)

De-initialize a data struct, freeing if necessary.

Parameters

[in,out]

data

The data to de-initialize, which must not be NULL.

Returns

Zero upon success.

Postcondition

The struct must be initialized before using again.

References BSL_SUCCESS.

Referenced by bsl_mock_eid_deinit(), and BSL_SecOutcome_Deinit().

BSL_Data_Init()

int BSL_Data_Init

(

BSL_Data_t *

data

)

Initialize an empty data struct.

Parameters

[in,out]

data

The data to initialize, which must not be NULL.

Returns

Zero upon success.

See also

BSL_DATA_INIT_NULL

References BSL_SUCCESS.

Referenced by BSL_Crypto_AddRegistryKey(), and bsl_mock_decode_eid().

BSL_Data_InitBuffer()

int BSL_Data_InitBuffer	(	BSL_Data_t *	data,
		size_t	bytelen
	)

Initialize with an owned buffer of size bytelen.

Todo:

Clarify to indicate this calls MALLOC.

Parameters

[in,out]	data	The data to initialize.
[in]	bytelen	Length of buffer to allocate.

Returns

Zero upon success.

References BSL_MALLOC, BSL_SUCCESS, BSL_Data_t::len, BSL_Data_t::owned, and BSL_Data_t::ptr.

Referenced by BSL_SecOutcome_Init().

BSL_Data_InitView()

int BSL_Data_InitView	(	BSL_Data_t *	data,
		size_t	len,
		BSL_DataPtr_t	src
	)

Initialize a data struct as an overlay on optional external data.

Parameters

[in,out]	data	The data to initialize, which must not be NULL.
[in]	len	The total length to allocate, which may be zero.
[in]	src	An optional source buffer to point to.

Returns

Zero upon success.

References BSL_SUCCESS, BSL_Data_t::len, BSL_Data_t::owned, and BSL_Data_t::ptr.

Referenced by BSL_AbsSecBlock_DecodeFromCBOR(), BSL_API_QuerySecurity(), and BSL_SecParam_GetAsBytestr().

BSL_Data_Resize()

int BSL_Data_Resize	(	BSL_Data_t *	data,
		size_t	len
	)

Resize the data, copying if necessary.

Parameters

[in,out]	data	The data to resize, which must not be NULL.
[in]	len	The new total size.

Returns

Zero upon success.

References BSL_ERR_INSUFFICIENT_SPACE, BSL_LOG_ERR, BSL_REALLOC, BSL_SUCCESS, BSL_Data_t::len, BSL_Data_t::owned, BSL_Data_t::ptr, and UNLIKELY.

Referenced by BSL_Data_AppendFrom(), and BSL_Data_CopyFrom().

BSL_Host_GetSecSrcEID()

int BSL_Host_GetSecSrcEID

(

BSL_HostEID_t *

eid

)

Get the local EID used when this node is a security source.

Parameters

[out]

eid

The EID to write into. This must already be initialized.

Returns

Zero if successful.

See also

BSL_ROLE_SOURCE

References BSL_HostDescriptors_t::get_host_eid_fn, and BSL_HostDescriptors_t::user_data.

BSL_HostEID_DecodeFromCBOR()

int BSL_HostEID_DecodeFromCBOR	(	BSL_HostEID_t *	eid,
		void *	decoder
	)

Load an EID from CBOR.

Parameters

[in,out]	eid	This eid
[in]	CBOR	decoder context

Returns

0 on success

References BSL_HostDescriptors_t::eid_from_cbor, and BSL_HostEID_t::handle.

Referenced by BSL_AbsSecBlock_DecodeFromCBOR().

BSL_HostEID_DecodeFromText()

int BSL_HostEID_DecodeFromText	(	BSL_HostEID_t *	eid,
		const char *	text
	)

Decode an EID from its text form.

Parameters

[out]	eid	The EID to write into. This must already be initialized.
[in]	text	The text to read from, which must be non-null.

Returns

Zero if successful.

References BSL_HostDescriptors_t::eid_from_text, BSL_HostEID_t::handle, and BSL_HostDescriptors_t::user_data.

BSL_HostEID_Deinit()

void BSL_HostEID_Deinit

(

BSL_HostEID_t *

eid

)

De-initialize an abstract EID.

Parameters

[in,out]

eid

The object to de-initialize.

References BSL_HostDescriptors_t::eid_deinit, and BSL_HostDescriptors_t::user_data.

Referenced by BSL_AbsSecBlock_Deinit().

BSL_HostEID_EncodeToCBOR()

int BSL_HostEID_EncodeToCBOR	(	const BSL_HostEID_t *	eid,
		void *	user_data
	)

Encode a EID into a CBOR sequence.

Parameters

[in]	eid
[in]	user_data

Returns

Zero if successful.

References BSL_HostDescriptors_t::eid_to_cbor.

Referenced by BSL_AbsSecBlock_EncodeToCBOR().

BSL_HostEID_Init()

int BSL_HostEID_Init

(

BSL_HostEID_t *

eid

)

Initialize an abstract EID.

Parameters

[out]

eid

The object to initialize.

Returns

Zero if successful.

References BSL_HostDescriptors_t::eid_init, and BSL_HostDescriptors_t::user_data.

Referenced by BSL_AbsSecBlock_DecodeFromCBOR().

BSL_HostEIDPattern_DecodeFromText()

int BSL_HostEIDPattern_DecodeFromText	(	BSL_HostEIDPattern_t *	pat,
		const char *	text
	)

Decode an EID Pattern from its text form.

Parameters

[out]	pat	The pattern to write into. This must already be initialized.
[in]	text	The text to read from, which must be non-null.

Returns

Zero if successful.

References BSL_HostDescriptors_t::eidpat_from_text, and BSL_HostDescriptors_t::user_data.

BSL_HostEIDPattern_Deinit()

void BSL_HostEIDPattern_Deinit

(

BSL_HostEIDPattern_t *

pat

)

De-initialize an abstract EID Pattern.

Parameters

[in,out]

pat

The object to de-initialize.

References BSL_HostDescriptors_t::eidpat_deinit, and BSL_HostDescriptors_t::user_data.

BSL_HostEIDPattern_Init()

int BSL_HostEIDPattern_Init

(

BSL_HostEIDPattern_t *

pat

)

Initialize an abstract EID Pattern.

Parameters

[out]

pat

The object to initialize.

Returns

Zero if successful.

References BSL_HostDescriptors_t::eidpat_init, and BSL_HostDescriptors_t::user_data.

BSL_HostEIDPattern_IsMatch()

bool BSL_HostEIDPattern_IsMatch	(	const BSL_HostEIDPattern_t *	pat,
		const BSL_HostEID_t *	eid
	)

Determine if an EID Pattern matches a specific EID.

Parameters

[in]	pat	The pattern to compare.
[in]	eid	The EID to compare.

Returns

True if the EID is a match to the pattern.

References BSL_HostDescriptors_t::eidpat_match, and BSL_HostDescriptors_t::user_data.

Referenced by BSLP_PolicyPredicate_IsMatch().

BSL_Log_DumpAsHexString()

uint8_t * BSL_Log_DumpAsHexString	(	uint8_t *	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.

Returns

The number of bytes written to dstbuf. It will not exceed dstlen.

Referenced by BSL_AbsSecBlock_Print(), test_RFC9173_AppendixA_Example2_BCB_Acceptor(), and test_RFC9173_AppendixA_Example2_BCB_Source().

BSL_LogEvent()

void BSL_LogEvent	(	int	severity,
		const char *	filename,
		int	lineno,
		const char *	funcname,
		const char *	format,
			...
	)

Log an event.

Parameters

	severity	The severity from a subset of the POSIX syslog values.
[in]	filename	The originating file name, which may include directory parts.
[in]	lineno	The originating file line number.
[in]	funcname	The originating function name.
[in]	format	The log message format string.
	...	Values for the format string.

References BSL_LogIsEnabledFor(), BSL_LogEvent_event_t::context, event_queue, BSL_LogEvent_event_t::message, BSL_LogEvent_event_t::severity, and thr_valid.

BSL_LogGetSeverity()

int BSL_LogGetSeverity	(	int *	severity,
		const char *	name
	)

Interpret a text name as a severity level.

Parameters

[out]	severity	The associated severity level.
[in]	name	The text name, which is case insensitive.

Returns

Zero if successful.

References CHKERR1.

BSL_LogIsEnabledFor()

bool BSL_LogIsEnabledFor

(

int

severity

)

Determine if a particular severity is being logged.

This function is multi-thread safe.

Parameters

severity

The severity from a subset of the POSIX syslog values.

Returns

True if the severity level will be logged.

See also

BSL_log_set_least_severity()

References least_severity.

Referenced by BSL_LogEvent().

BSL_LogSetLeastSeverity()

void BSL_LogSetLeastSeverity

(

int

severity

)

Set the least severity enabled for logging.

Other events will be dropped by the logging facility. This function is multi-thread safe.

Parameters

severity

The severity from a subset of the POSIX syslog values.

See also

BSL_log_is_enabled_for()

References least_severity.

BSL_openlog()

void BSL_openlog

(

void

)

Opens the event log.

Note

This should be called once per process, not thread or library instance. At the end of the process there should be a call to BSL_closelog()

This is a mimic to POSIX openlog()

References BSL_LOG_QUEUE_SIZE, event_queue, BSL_LogEvent_event_t::message, BSL_LogEvent_event_t::severity, thr_sink, and thr_valid.

BSL_PolicyRegistry_FinalizeActions()

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

Finalizes policy provider for sec ops & sec results for a bundle.

Parameters

[in]	bsl	BSL library context
[in]	policy_actions	A policy action set, which may contain error codes and other info. [Zeroed, pre-allocated and memory owned by caller] Caller-allocated, zeroed space for action set
[in,out]	bundle	Bundle seeking security operations
[in]	response_output	results from security context
[in]	location	Where in the BPA lifecycle this query arises from

Returns

0 if success

Referenced by BSL_API_ApplySecurity().

BSL_PolicyRegistry_InspectActions()

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

Queries the policy provider for any security operations to take on the bundle.

Note

The caller is obligated to allocate space for the policy_action_set output. This memory must be zeroed before being passed, doing otherwise will raise an assertion.

Parameters

[in]	bsl	BSL library context
[out]	output_action_set	policy action set, which may contain error codes and other info. [Zeroed, pre-allocated and memory owned by caller] Caller-allocated, zeroed space for action set
[in,out]	bundle	Bundle seeking security operations
[in]	location	Where in the BPA lifecycle this query arises from

Returns

0 if success

Referenced by BSL_API_QuerySecurity(), test_PolicyProvider_Inspect_RFC9173_BIB(), test_PolicyProvider_InspectEmptyRuleset(), and test_PolicyProvider_InspectSingleBIBRuleset().

BSL_SecCtx_ExecutePolicyActionSet()

int BSL_SecCtx_ExecutePolicyActionSet	(	BSL_LibCtx_t *	lib,
		BSL_SecurityResponseSet_t *	output_response,
		BSL_BundleRef_t *	bundle,
		const BSL_SecurityActionSet_t *	action_set
	)

Call the underlying security context to perform the given action.

Parameters

[in]	lib	This BSL context
[out]	output_response	Pointer to allocated, zeroed memory into which the response is populated
[in,out]	bundle	Pointer to bundle, which may be modified.
[in]	action_set	Action containing all params and operations.

Returns

0 on success, negative on failure.

Notes:

• It should evaluate every security operation, even if earlier ones failed.
• The outcome can indicate in the policy action response how exactly it fared (pass, fail, etc)
• BCB will be a special case, since it actively manipulates the BTSD

References BSL_CALLOC, BSL_FREE, BSL_LOG_ERR, BSL_SECOP_CONCLUSION_FAILURE, BSL_SECOP_CONCLUSION_SUCCESS, BSL_SecOper_IsBIB(), BSL_SecOper_IsRoleSource(), BSL_SecOper_SetConclusion(), BSL_SecurityActionSet_CountOperations(), BSL_SecurityActionSet_IsConsistent(), BSL_SecurityResponseSet_Init(), and BSL_SUCCESS.

Referenced by BSL_API_ApplySecurity(), test_SecurityContext_BIB_Acceptor(), test_SecurityContext_BIB_Source(), test_SecurityContext_BIB_Verifier(), and test_SecurityContext_BIB_Verifier_Failure().

BSL_SecCtx_ValidatePolicyActionSet()

bool BSL_SecCtx_ValidatePolicyActionSet	(	BSL_LibCtx_t *	lib,
		const BSL_BundleRef_t *	bundle,
		const BSL_SecurityActionSet_t *	action_set
	)

Todo:

Doxygen

Referenced by BSL_API_QuerySecurity().

BSL_SecOper_AppendParam()

void BSL_SecOper_AppendParam	(	BSL_SecOper_t *	self,
		const BSL_SecParam_t *	param
	)

Add the given security parameter to this list of parameters.

Todo:

Clarify pointer/copy semantics.

Parameters

[in,out]	self	This security operation
[in]	param	Security parameter to include.

References BSL_SecOper_IsConsistent(), and BSL_SecParam_IsConsistent().

Referenced by BSLP_PolicyRule_EvaluateAsSecOper().

BSL_SecOper_CountParams()

size_t BSL_SecOper_CountParams

(

const BSL_SecOper_t *

self

)

Get the count of parameters contained within this security operation.

Parameters

self	This security operation.

Returns

Count of security parameters.

References BSL_SecOper_IsConsistent().

Referenced by BSLX_BIB_InitFromSecOper(), and test_PolicyProvider_Inspect_RFC9173_BIB().

BSL_SecOper_Deinit()

void BSL_SecOper_Deinit

(

BSL_SecOper_t *

self

)

Empty and release any resources used internally by this structure.

Certain backend implementations may create dynamic data structures that may need to be cleaned up, so it is essential to call this under all circumstances.

Parameters

[in,out]

self

Non-NULL pointer to this security operation

References BSL_SecOper_IsConsistent().

Referenced by test_RFC9173_AppendixA_Example1_BIB_Source(), test_RFC9173_AppendixA_Example2_BCB_Acceptor(), and test_RFC9173_AppendixA_Example2_BCB_Source().

BSL_SecOper_GetConclusion()

BSL_SecOper_ConclusionState_e BSL_SecOper_GetConclusion

(

const BSL_SecOper_t *

self

)

Retrieve the conclusion state of a security operation.

Parameters

[in]

self

The security operation

Returns

the conclusion state

References BSL_SecOper_IsConsistent().

Referenced by BSL_API_ApplySecurity().

BSL_SecOper_GetParamAt()

const BSL_SecParam_t * BSL_SecOper_GetParamAt	(	const BSL_SecOper_t *	self,
		size_t	index
	)

Returns a pointer to the Security Parameter at a given index in the list of all parameters.

Todo:

Clarify behavior if index is out of range.

Parameters

[in]	self	This security operation
[in]	index	Index of security parameter list to retrieve from

Returns

Pointer to security parameter type at given index.

References BSL_SecOper_IsConsistent().

Referenced by BSLX_BIB_InitFromSecOper().

BSL_SecOper_GetSecurityBlockNum()

uint64_t BSL_SecOper_GetSecurityBlockNum

(

const BSL_SecOper_t *

self

)

Get the block number of the security block containing this sec operation.

Parameters

[in]

self

This security operation

References BSL_SecOper_IsConsistent().

Referenced by BSLP_QueryPolicy().

BSL_SecOper_GetTargetBlockNum()

uint64_t BSL_SecOper_GetTargetBlockNum

(

const BSL_SecOper_t *

self

)

Get the block number of the target block covered by this security operation.

Parameters

[in]

self

This security operation

References BSL_SecOper_IsConsistent().

Referenced by BSLP_QueryPolicy().

BSL_SecOper_Init()

void BSL_SecOper_Init

(

BSL_SecOper_t *

self

)

Initialize a newly allocated structure.

Parameters

[in,out]

self

Non-NULL pointer to this security operation

References BSL_SecOper_IsConsistent().

Referenced by BSLP_QueryPolicy(), and test_SamplePolicyProvider_WildcardPolicyRuleVerifiesBIB().

BSL_SecOper_InitSet()

void BSL_SecOper_InitSet	(	BSL_SecOper_t *	self,
		const BSL_SecOper_t *	src
	)

Initialize from a copy.

Parameters

[in,out]	self	Non-NULL pointer to this security operation
[in]	src	Non-NULL pointer to this source to copy from.

References BSL_SecOper_IsConsistent().

BSL_SecOper_IsBIB()

bool BSL_SecOper_IsBIB

(

const BSL_SecOper_t *

self

)

Return true if this security operation is BIB.

Parameters

[in]

self

This security operation

Returns

boolean

References BSL_SECBLOCKTYPE_BIB, and BSL_SecOper_IsConsistent().

Referenced by BSL_SecCtx_ExecutePolicyActionSet(), BSLP_QueryPolicy(), and test_SamplePolicyProvider_WildcardPolicyRuleVerifiesBIB().

BSL_SecOper_IsConsistent()

bool BSL_SecOper_IsConsistent

(

const BSL_SecOper_t *

self

)

Returns true if internal consistency and sanity checks pass.

Todo:

Formalize invariants

Parameters

[in]

self

This security operation

Returns

True if consistent, may assert false otherwise.

References BSL_SECBLOCKTYPE_BCB, BSL_SECBLOCKTYPE_BIB, BSL_SECOP_CONCLUSION_FAILURE, BSL_SECOP_CONCLUSION_PENDING, BSL_SECROLE_ACCEPTOR, BSL_SECROLE_SOURCE, and BSL_SECROLE_VERIFIER.

Referenced by BSL_SecOper_AppendParam(), BSL_SecOper_CountParams(), BSL_SecOper_Deinit(), BSL_SecOper_GetConclusion(), BSL_SecOper_GetParamAt(), BSL_SecOper_GetSecurityBlockNum(), BSL_SecOper_GetTargetBlockNum(), BSL_SecOper_Init(), BSL_SecOper_InitSet(), BSL_SecOper_IsBIB(), BSL_SecOper_IsRoleAcceptor(), BSL_SecOper_IsRoleSource(), BSL_SecOper_IsRoleVerifier(), BSL_SecOper_Populate(), BSL_SecOper_Set(), BSL_SecOper_SetConclusion(), and BSL_SecOutcome_Init().

BSL_SecOper_IsRoleAcceptor()

bool BSL_SecOper_IsRoleAcceptor

(

const BSL_SecOper_t *

self

)

Return true if this security operation's role is Acceptor.

Parameters

[in]

self

This Security Operation

Returns

boolean

References BSL_SecOper_IsConsistent(), and BSL_SECROLE_ACCEPTOR.

BSL_SecOper_IsRoleSource()

bool BSL_SecOper_IsRoleSource

(

const BSL_SecOper_t *

self

)

Return true if this security operation's role is SOURCE.

Parameters

[in]

self

This Security Operation

Returns

boolean

References BSL_SecOper_IsConsistent(), and BSL_SECROLE_SOURCE.

Referenced by BSL_SecCtx_ExecutePolicyActionSet(), and BSLP_QueryPolicy().

BSL_SecOper_IsRoleVerifier()

bool BSL_SecOper_IsRoleVerifier

(

const BSL_SecOper_t *

self

)

Return true if this security operation's role is Verifier.

Parameters

[in]

self

This Security Operation

Returns

boolean

References BSL_SecOper_IsConsistent(), and BSL_SECROLE_VERIFIER.

BSL_SecOper_Populate()

void BSL_SecOper_Populate	(	BSL_SecOper_t *	self,
		uint64_t	context_id,
		uint64_t	target_block_num,
		uint64_t	sec_block_num,
		BSL_SecBlockType_e	sec_type,
		BSL_SecRole_e	sec_role,
		BSL_PolicyAction_e	failure_code
	)

Populate an initialized Security Operation with the given values.

Parameters

[in,out]	self	Non-NULL pointer to this security operation.
[in]	context_id	ID of the security context
[in]	target_block_num	Block ID of security target block
[in]	sec_block_num	Block ID of security block.
[in]	sec_type	Member of BSL_SecBlockType_e enum indicating BIB or BCB
[in]	sec_role	Member of BSL_SecRole_e enum indicating role.

References BSL_SECOP_CONCLUSION_PENDING, and BSL_SecOper_IsConsistent().

Referenced by BSLP_PolicyRule_EvaluateAsSecOper().

BSL_SecOper_Set()

void BSL_SecOper_Set	(	BSL_SecOper_t *	self,
		const BSL_SecOper_t *	src
	)

Set from a copy.

Parameters

[in,out]	self	Non-NULL pointer to this security operation
[in]	src	Non-NULL pointer to this source to copy from.

References BSL_SecOper_IsConsistent().

BSL_SecOper_SetConclusion()

void BSL_SecOper_SetConclusion	(	BSL_SecOper_t *	self,
		BSL_SecOper_ConclusionState_e	new_conclusion
	)

Set the security operation conclusion state.

Parameters

[in,out]	self	security operation to change conclusion state of
[in]	new_conclusion	new conclusion to set to

References BSL_SecOper_IsConsistent().

Referenced by BSL_SecCtx_ExecutePolicyActionSet(), and BSLP_QueryPolicy().

BSL_SecOutcome_AppendParam()

void BSL_SecOutcome_AppendParam	(	BSL_SecOutcome_t *	self,
		const BSL_SecParam_t *	param
	)

Append a Security Parameter to this outcome.

Todo:

Double-check copy semantics.

Parameters

[in,out]	self	Non-NULL pointer to this security outcome.
[in]	param	Non-NULL pointer to security parameter to copy and append.

References BSL_SecParam_IsConsistent().

BSL_SecOutcome_AppendResult()

void BSL_SecOutcome_AppendResult	(	BSL_SecOutcome_t *	self,
		const BSL_SecResult_t *	sec_result
	)

Append a Security Result to this outcome.

Todo:

Double-check copy semantics.

Parameters

[in,out]	self	Non-NULL pointer to this security outcome.
[in]	sec_result	Non-NULL pointer to security result to copy and append.

References BSL_SecResult_IsConsistent().

BSL_SecOutcome_CountParams()

size_t BSL_SecOutcome_CountParams

(

const BSL_SecOutcome_t *

self

)

Returns number of parameters in this outcome.

Parameters

[in]

self

This outcome

Returns

Number of parameters

BSL_SecOutcome_CountResults()

size_t BSL_SecOutcome_CountResults

(

const BSL_SecOutcome_t *

self

)

Get the number of results.

Parameters

[in]

self

this sec outcome

Returns

number of results in sec outcome

BSL_SecOutcome_Deinit()

void BSL_SecOutcome_Deinit

(

BSL_SecOutcome_t *

self

)

Release any resources owned by this security outcome.

Parameters

[in,out]

self

Non-Null pointer to this security outcome.

References BSL_Data_Deinit().

BSL_SecOutcome_GetParamAt()

const BSL_SecParam_t * BSL_SecOutcome_GetParamAt	(	const BSL_SecOutcome_t *	self,
		size_t	index
	)

Get the security parameter from the security outcome at the provided index.

Parameters

[in]	self	security outcome
[in]	index	index to retrieve security parameter from

Returns

Security parameter

BSL_SecOutcome_GetResultAtIndex()

const BSL_SecResult_t * BSL_SecOutcome_GetResultAtIndex	(	const BSL_SecOutcome_t *	self,
		size_t	index
	)

Get the result at index i.

Panics if i is out of range.

Parameters

[in]	self	This outcome
[in]	index	Index in the list to retrieve

Returns

Sec Result at index

BSL_SecOutcome_Init()

void BSL_SecOutcome_Init	(	BSL_SecOutcome_t *	self,
		const BSL_SecOper_t *	sec_oper,
		size_t	allocation_size
	)

Populate a pre-allocated security outcome struct.

Parameters

[in,out]	self	Non-Null pointer to this security outcome.
[in]	sec_oper	Security operation containing the necessary info.
[in]	allocation_size	Size of working space to allocate.

References BSL_Data_InitBuffer(), and BSL_SecOper_IsConsistent().

BSL_SecOutcome_IsConsistent()

bool BSL_SecOutcome_IsConsistent

(

const BSL_SecOutcome_t *

self

)

Return true if internal invariants hold.

Parameters

[in]

self

This sec outcome.

Returns

true if invariants hold

BSL_SecOutcome_IsInAbsSecBlock()

bool BSL_SecOutcome_IsInAbsSecBlock	(	const BSL_SecOutcome_t *	self,
		const BSL_AbsSecBlock_t *	abs_sec_block
	)

Returns true if this (the parameters and results) is contained within the given ASK.

Todo:

Can move to backend

Parameters

[in]	self
[in]	outcome

Returns

References BSL_AbsSecBlock_IsConsistent(), BSL_LOG_DEBUG, and BSL_LOG_ERR.

BSL_SecParam_GetAsBytestr()

int BSL_SecParam_GetAsBytestr	(	const BSL_SecParam_t *	self,
		BSL_Data_t *	result
	)

Retrieve bytestring value of result when security parameter type is bytestring.

WARNING: Always check type before using.

Todo:

Clarify whether result contains copy or view of content

Parameters

[in]	self	This Security Parameter
[in,out]	result	Pointer to pre-allocated data into which the bytestring is copied.

Returns

Negative on error.

References BSL_Data_InitView(), and BSL_SecParam_IsConsistent().

Referenced by BSL_AbsSecBlock_EncodeToCBOR(), and BSLX_BIB_InitFromSecOper().

BSL_SecParam_GetAsUInt64()

uint64_t BSL_SecParam_GetAsUInt64

(

const BSL_SecParam_t *

self

)

Retrieve integer value of result when this result type is integer.

Warning

Always check using BSL_SecParam_IsInt64() first.

Parameters

[in]

self

This Security Parameter

Returns

Integer value of parameter if present, panics/aborts otherwise.

References BSL_SECPARAM_TYPE_INT64.

Referenced by BSL_AbsSecBlock_EncodeToCBOR(), and BSLX_BIB_InitFromSecOper().

BSL_SecParam_GetId()

uint64_t BSL_SecParam_GetId

(

const BSL_SecParam_t *

self

)

Get parameter ID of this param.

Parameters

[in]

self

This BPSec Param type

Returns

References BSL_SecParam_IsConsistent().

Referenced by BSLX_BIB_InitFromSecOper().

BSL_SecParam_InitBytestr()

int BSL_SecParam_InitBytestr	(	BSL_SecParam_t *	self,
		uint64_t	param_id,
		BSL_Data_t	value
	)

Initialize as a parameter containing a bytestring.

Parameters

[in,out]	self	This Security Parameter
[in]	param_id	ID of the parameter
[in]	value	View of bytes, which get copied into this Security Parameter.

Returns

Negative on an error.

References BSL_SECPARAM_TYPE_BYTESTR, BSL_SUCCESS, BSL_Data_t::len, and BSL_Data_t::ptr.

Referenced by BSL_AbsSecBlock_DecodeFromCBOR().

BSL_SecParam_InitInt64()

int BSL_SecParam_InitInt64	(	BSL_SecParam_t *	self,
		uint64_t	param_id,
		uint64_t	value
	)

Initialize as a parameter containing an integer as a value.

Parameters

[in,out]	self	This Security Parameter
[in]	param_id	ID of the parameter
[in]	value	View of bytes, which get copied into this Security Parameter.

Returns

Negative on an error.

References BSL_SECPARAM_TYPE_INT64, and BSL_SUCCESS.

Referenced by BSL_AbsSecBlock_DecodeFromCBOR().

BSL_SecParam_InitStr()

int BSL_SecParam_InitStr	(	BSL_SecParam_t *	self,
		uint64_t	param_id,
		const char *	value
	)

Parameters

[in,out]	self	This Security Parameter
[in]	param_id	ID of the parameter
[in]	value	text string of the parameter, copied into self

Returns

Negative on an error.

References BSL_SUCCESS.

BSL_SecParam_IsConsistent()

bool BSL_SecParam_IsConsistent

(

const BSL_SecParam_t *

self

)

Return true if invariant conditions pass.

Parameters

[in]

self

This security parameter

Returns

true if valid, false otherwise.

References BSL_SECPARAM_TYPE_INT64, and BSL_SECPARAM_TYPE_UNKNOWN.

Referenced by BSL_SecOper_AppendParam(), BSL_SecOutcome_AppendParam(), BSL_SecParam_GetAsBytestr(), BSL_SecParam_GetId(), and BSLP_PolicyRule_AddParam().

BSL_SecParam_IsInt64()

int BSL_SecParam_IsInt64

(

const BSL_SecParam_t *

self

)

Returns true when the value type is an integer.

Parameters

[in]

self

This Security Parameter

Returns

True when value type is integer.

References BSL_SECPARAM_TYPE_INT64.

Referenced by BSL_AbsSecBlock_EncodeToCBOR(), and BSLX_BIB_InitFromSecOper().

BSL_SecParam_IsParamIDOutput()

bool BSL_SecParam_IsParamIDOutput

(

uint64_t

param_id

)

Indicates true when this parameter is NOT an implementation-specific security parameter.

Todo:

Rename to avoid using negative logic and clarify.

Parameters

param_id

ID of the parameter

Returns

True when this is NOT an internal parameter ID.

References BSL_SECPARAM_TYPE_INT_STARTINDEX.

BSL_SecResult_Init()

int BSL_SecResult_Init	(	BSL_SecResult_t *	self,
		uint64_t	result_id,
		uint64_t	context_id,
		uint64_t	target_block_num,
		BSL_Data_t	content
	)

Populate a pre-allocated result.

Parameters

[in,out]	self	Non-NULL pointer to allocated result.
[in]	result_id	Result ID of corresponding result bytestring, meaning dependent on security context.
[in]	context_id	ID of security context.
[in]	target_block_num	Target of the given security result, included here for convenience.
[in]	content	Read-only view to data containing the bytes of the security result, which is copied out of here.

Returns

0 on success, negative on error

References BSL_SecResult_IsConsistent(), BSL_SUCCESS, BSL_Data_t::len, and BSL_Data_t::ptr.

Referenced by BSL_AbsSecBlock_DecodeFromCBOR().

BSL_SecResult_IsConsistent()

bool BSL_SecResult_IsConsistent

(

const BSL_SecResult_t *

self

)

Return true when internal invariant checks pass.

Parameters

self	This security result

Referenced by BSL_SecOutcome_AppendResult(), and BSL_SecResult_Init().

BSL_SecurityAction_AppendSecOper()

int BSL_SecurityAction_AppendSecOper	(	BSL_SecurityAction_t *	self,
		BSL_SecOper_t *	sec_oper
	)

Add security operation to security action, with deterministic ordering.

Parameters

[in,out]	self	action to add security operation to
[in,out]	sec_oper	new security operation to add and move from.

Returns

0 if successful

References BSL_SUCCESS.

BSL_SecurityAction_CountErrors()

size_t BSL_SecurityAction_CountErrors

(

const BSL_SecurityAction_t *

self

)

Returns count of failures after processing this action.

Parameters

[in]

self

Pointer to this security action.

Returns

Count of errors.

BSL_SecurityAction_CountSecOpers()

size_t BSL_SecurityAction_CountSecOpers

(

const BSL_SecurityAction_t *

self

)

Returns

number of security operation in the

Parameters

[in]

self

action

BSL_SecurityAction_Deinit()

void BSL_SecurityAction_Deinit

(

BSL_SecurityAction_t *

self

)

De-initialize security action.

Parameters

[in,out]

self

security action

BSL_SecurityAction_GetSecOperAtIndex()

BSL_SecOper_t * BSL_SecurityAction_GetSecOperAtIndex	(	const BSL_SecurityAction_t *	self,
		size_t	index
	)

Returns

the security operation at

Parameters

[in]	index	index in
[in]	self	security action

BSL_SecurityAction_IncrError()

void BSL_SecurityAction_IncrError

(

BSL_SecurityAction_t *

self

)

Increment a security failure for this action set.

Parameters

[in,out]

self

Pointer to this security action set.

BSL_SecurityAction_Init()

void BSL_SecurityAction_Init

(

BSL_SecurityAction_t *

self

)

Initialize security action.

Parameters

[out]

self

security action

BSL_SecurityAction_InitSet()

void BSL_SecurityAction_InitSet	(	BSL_SecurityAction_t *	self,
		const BSL_SecurityAction_t *	src
	)

Initialize from a copy.

Parameters

[out]	self	security action
[in]	src	The source of the copy.

BSL_SecurityAction_IsConsistent()

bool BSL_SecurityAction_IsConsistent

(

const BSL_SecurityAction_t *

self

)

Returns

true if security action

Parameters

self	is consistent

BSL_SecurityAction_OrderSecOps()

int BSL_SecurityAction_OrderSecOps

(

BSL_SecurityAction_t *

self

)

Order the Security operations such that execution will be successful.

Parameters

[in,out]

self

action to sort

BSL_SecurityAction_Sizeof()

size_t BSL_SecurityAction_Sizeof

(

void

)

Returns

size of security operation

BSL_SecurityActionSet_AppendAction()

int BSL_SecurityActionSet_AppendAction	(	BSL_SecurityActionSet_t *	self,
		const BSL_SecurityAction_t *	action
	)

Append a security operation to the security action set.

Parameters

[in,out]	self	This security action set.
[in]	action	Action to include.

Returns

0 on success, negative on error

References BSL_SUCCESS.

Referenced by BSLP_QueryPolicy().

BSL_SecurityActionSet_CountActions()

size_t BSL_SecurityActionSet_CountActions

(

const BSL_SecurityActionSet_t *

self

)

Count number of security operations present in this policy action set.

Parameters

[in]

self

This action set.

Returns

Number of actions, 0 indicates no policy matched.

Referenced by test_PolicyProvider_InspectEmptyRuleset(), and test_PolicyProvider_InspectSingleBIBRuleset().

BSL_SecurityActionSet_CountErrors()

size_t BSL_SecurityActionSet_CountErrors

(

const BSL_SecurityActionSet_t *

self

)

Returns count of failures after processing this action set.

Parameters

[in]

self

Pointer to this security action set.

Returns

Count of errors.

Referenced by BSLP_QueryPolicy().

BSL_SecurityActionSet_CountOperations()

size_t BSL_SecurityActionSet_CountOperations

(

const BSL_SecurityActionSet_t *

self

)

Returns

the total number of operations within each of the actions of

Parameters

self	action set

Referenced by BSL_SecCtx_ExecutePolicyActionSet().

BSL_SecurityActionSet_Deinit()

void BSL_SecurityActionSet_Deinit

(

BSL_SecurityActionSet_t *

self

)

Zeroize, clear, and release itself and any owned resources.

Parameters

[in,out]

self

This action set.

Referenced by test_PolicyProvider_Inspect_RFC9173_BIB(), test_PolicyProvider_InspectEmptyRuleset(), test_PolicyProvider_InspectSingleBIBRuleset(), test_SecurityContext_BIB_Acceptor(), test_SecurityContext_BIB_Source(), test_SecurityContext_BIB_Verifier(), and test_SecurityContext_BIB_Verifier_Failure().

BSL_SecurityActionSet_GetActionAtIndex()

const BSL_SecurityAction_t * BSL_SecurityActionSet_GetActionAtIndex	(	const BSL_SecurityActionSet_t *	self,
		size_t	index
	)

Returns the Security Operation at the given index.

Parameters

[in]	self	This action set
[in]	index	index

Returns

pointer to action at given index, asserting false if not in bound

Referenced by test_PolicyProvider_Inspect_RFC9173_BIB(), test_PolicyProvider_InspectEmptyRuleset(), test_PolicyProvider_InspectSingleBIBRuleset(), and test_SecurityContext_BIB_Verifier_Failure().

BSL_SecurityActionSet_Init()

void BSL_SecurityActionSet_Init

(

BSL_SecurityActionSet_t *

self

)

Initialize a new security action set.

Parameters

[in,out]

self

This pre-allocated action set

Referenced by BSLP_QueryPolicy().

BSL_SecurityActionSet_IsConsistent()

bool BSL_SecurityActionSet_IsConsistent

(

const BSL_SecurityActionSet_t *

self

)

Return true if internal sanity and consistency checks pass.

Parameters

[in]

self

This action set.

Returns

true if action set is consistent

Referenced by BSL_SecCtx_ExecutePolicyActionSet(), and BSLP_QueryPolicy().

BSL_SecurityActionSet_Sizeof()

size_t BSL_SecurityActionSet_Sizeof

(

void

)

Returns size of the struct, helpful for dynamic allocation.

Returns

Size of the struct

BSL_SecurityResponseSet_CountResponses()

size_t BSL_SecurityResponseSet_CountResponses

(

const BSL_SecurityResponseSet_t *

self

)

Return number of responses (operations acted upon)

Parameters

[in]

self

This response set.

References BSL_SecurityResponseSet_IsConsistent().

BSL_SecurityResponseSet_Deinit()

void BSL_SecurityResponseSet_Deinit

(

BSL_SecurityResponseSet_t *

self

)

Zeroize itself and release any owned resources.

Parameters

[in,out]

self

This response set.

References BSL_SecurityResponseSet_IsConsistent().

Referenced by test_SecurityContext_BIB_Acceptor(), test_SecurityContext_BIB_Source(), test_SecurityContext_BIB_Verifier(), and test_SecurityContext_BIB_Verifier_Failure().

BSL_SecurityResponseSet_Init()

void BSL_SecurityResponseSet_Init	(	BSL_SecurityResponseSet_t *	self,
		size_t	noperations,
		size_t	nfailed
	)

Initialize with the given count of operations and failures.

Todo:

This is still undefined.

Referenced by BSL_SecCtx_ExecutePolicyActionSet().

BSL_SecurityResponseSet_IsConsistent()

bool BSL_SecurityResponseSet_IsConsistent

(

const BSL_SecurityResponseSet_t *

self

)

Return true if internal consistency checks pass.

Parameters

[in]

self

This response set.

Referenced by BSL_SecurityResponseSet_CountResponses(), and BSL_SecurityResponseSet_Deinit().

BSL_SeqReader_Deinit()

int BSL_SeqReader_Deinit

(

BSL_SeqReader_t *

obj

)

Release resources from a sequential reader.

Parameters

[in,out]

obj

The reader handle.

Returns

Zero if successful.

References BSL_SUCCESS.

BSL_SeqReader_Get()

int BSL_SeqReader_Get	(	BSL_SeqReader_t *	obj,
		uint8_t *	buf,
		size_t *	bufsize
	)

Iterate a sequential reader.

Parameters

[in,out]	obj	The reader handle.
[out]	buf	The output buffer to fill.
[in,out]	bufsize	The available output buffer size as input, set to the used buffer size as output.

Returns

Zero if successful.

References BSL_SUCCESS.

Referenced by BSL_AuthCtx_DigestSeq(), and BSL_Cipher_AddSeq().

BSL_SeqWriter_Deinit()

int BSL_SeqWriter_Deinit

(

BSL_SeqWriter_t *

obj

)

Release resources from a sequential writer.

Parameters

[in,out]

obj

The writer handle.

Returns

Zero if successful.

References BSL_SUCCESS.

BSL_SeqWriter_Put()

int BSL_SeqWriter_Put	(	BSL_SeqWriter_t *	obj,
		const uint8_t *	buf,
		size_t *	bufsize
	)

Iterate a sequential writer.

Parameters

	obj	The writer handle.
[in]	buf	The input buffer to copy from.
[in,out]	bufsize	The available input buffer size as input, set to the used buffer size as output.

Returns

Zero if successful.

References BSL_SUCCESS.

Referenced by BSL_Cipher_AddSeq(), and BSL_Cipher_FinalizeSeq().