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 "BPSecLib_Public.h"

Include dependency graph for BPSecLib_Private.h:

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

Go to the source code of this file.

Data Structures
struct	BSL_Data_s
	Heap data storage and views. More...
struct	BSL_BundleTimestamp_s
	Creation Timestamp Defined in Section 4.2.7 of RFC 9171 [3]. More...
struct	BSL_PolicyDesc_s
	Descriptor of opaque data and callbacks for Policy Provider. More...
struct	BSL_SecCtxDesc_s
	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   { .owned = false, .ptr = NULL, .len = 0 }
	Static initializer for a data store.
#define	BSL_HOSTEID_INIT_INVALID   { .handle = NULL }
	Static initializer for an invalid BSL_HostEID_t.
#define	BSL_HOSTEID_INIT_INVALID   { .handle = NULL }
	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 struct BSL_Data_s	BSL_Data_t
	Heap data storage and views.
typedef struct BSL_SeqReader	BSL_SeqReader_t
	Forward declaration for file-like sequential reader.
typedef struct BSL_SeqWriter	BSL_SeqWriter_t
	Forward-declaration for file-like interface for a sequential writer.
typedef struct BSL_BundleTimestamp_s	BSL_BundleTimestamp_t
	Creation Timestamp Defined in Section 4.2.7 of RFC 9171 [3].
typedef struct BSL_SecResult_s	BSL_SecResult_t
	Represents a security result, being a 2-tuple of (result-id, bytes).
typedef struct BSL_SecParam_s	BSL_SecParam_t
	Represents a security parameter in an ASB as defined in RFC9172.
typedef struct BSL_SecOper_s	BSL_SecOper_t
	Represents a Security Operation produced by a policy provider to inform the security context.
typedef struct BSL_AbsSecBlock_s	BSL_AbsSecBlock_t
	Forward declaration of BSL_AbsSecBlock_t.
typedef struct BSL_SecOutcome_s	BSL_SecOutcome_t
	Represents the output following execution of a security operation.
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 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 }
	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_BIB = 11 , BSL_BLOCK_TYPE_BCB = 12 }
	Block types using IANA-assigned code points from [4]. More...
enum	BSL_BundleASBFlag_e { BSL_ASB_FLAG_PARAMS = 1 }
	Flags of the Abstract Security Block [1]. 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 }
	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_INT_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 Paramter 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 bytestream to a given target buffer.
void	BSL_openlog (void)
	Opens the event log.
void	BSL_closelog (void)
	Closes the event log.
void	BSL_LogEvent (int severity, const char *filename, int lineno, const char *funcname, const char *format,...)
	Log an event.
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[array_count], 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_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 SecResult.
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_t.
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 paramter.
size_t	BSL_SecParam_Sizeof (void)
	Return size of BSL_SecParam_t 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_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, 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 a pre-allocated Security Operation with the given values.
void	BSL_SecOper_Deinit (BSL_SecOper_t *self)
	Empty and release any resources used internally by this structure.
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 paramters.
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_IsRoleAccepter (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.
size_t	BSL_AbsSecBlock_Sizeof (void)
	Returns the size of the AbsSecBlock struct in bytes.
void	BSL_AbsSecBlock_Init (BSL_AbsSecBlock_t *self, uint64_t sec_context_id, BSL_HostEID_t source_eid)
	Populate a pre-allocated Absract 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 tarets, 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.
int	BSL_AbsSecBlock_EncodeToCBOR (const BSL_AbsSecBlock_t *self, BSL_Data_t allocated_target)
	Encodes this ASB into a CBOR string into the space pre-allocated indicated by the argument.
int	BSL_AbsSecBlock_DecodeFromCBOR (BSL_AbsSecBlock_t *self, 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_t 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)
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_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_IncrError (BSL_SecurityActionSet_t *self)
	Increment a security failure for this action set.
size_t	BSL_SecurityActionSet_CountErrors (const BSL_SecurityActionSet_t *self)
	Returns count of failures after processing this action set.
void	BSL_SecurityActionSet_Deinit (BSL_SecurityActionSet_t *self)
	Zeroize, clear, and release itself and any owned resources.
int	BSL_SecurityActionSet_AppendSecOper (BSL_SecurityActionSet_t *self, const BSL_SecOper_t *sec_oper)
	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_CountSecOpers (const BSL_SecurityActionSet_t *self)
	Count number of security operations present in this policy action set.
const BSL_SecOper_t *	BSL_SecurityActionSet_GetSecOperAtIndex (const BSL_SecurityActionSet_t *self, size_t index)
	Returns the Security Operation at the given index.
int	BSL_SecurityActionSet_GetErrCode (const BSL_SecurityActionSet_t *self)
	Get the error code after querying (inspecting) policy actions.
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 nailures.
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_SecCtx_ExecutePolicyActionSet (BSL_LibCtx_t *lib, BSL_SecurityResponseSet_t *output_response, BSL_BundleRef_t *bundle, const BSL_SecurityActionSet_t *action_set)
	Call the underying 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 requring 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

Definition in file BPSecLib_Private.h.

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

Definition at line 91 of file BPSecLib_Private.h.

ASSERT_ARG_EXPR

#define ASSERT_ARG_EXPR

(

expr

)

ASSERT_TEMPL(expr, "Panic: Argument expression check failed to satisfy")

Definition at line 248 of file BPSecLib_Private.h.

ASSERT_ARG_NONNULL

#define ASSERT_ARG_NONNULL

(

var

)

ASSERT_TEMPL((var) != NULL, "Panic: Null Argument check failed to satisfy")

Definition at line 250 of file BPSecLib_Private.h.

ASSERT_POSTCONDITION

#define ASSERT_POSTCONDITION

(

expr

)

ASSERT_TEMPL(expr, "Panic: Precondition failed to satisfy")

Definition at line 256 of file BPSecLib_Private.h.

ASSERT_PRECONDITION

#define ASSERT_PRECONDITION

(

expr

)

ASSERT_TEMPL(expr, "Panic: Precondition failed to satisfy")

Definition at line 254 of file BPSecLib_Private.h.

ASSERT_PROPERTY

#define ASSERT_PROPERTY

(

expr

)

ASSERT_TEMPL(expr, "Panic: Property check failed to satisfy")

Definition at line 252 of file BPSecLib_Private.h.

ASSERT_TEMPL

#define ASSERT_TEMPL	(		expr,
			msg
	)

Value:

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

Definition at line 237 of file BPSecLib_Private.h.

BSL_DATA_INIT_NULL

#define BSL_DATA_INIT_NULL   { .owned = false, .ptr = NULL, .len = 0 }

Static initializer for a data store.

See also

BSL_Data_Init()

Definition at line 279 of file BPSecLib_Private.h.

BSL_DEFAULT_BYTESTR_LEN

#define BSL_DEFAULT_BYTESTR_LEN   (128)

Definition at line 572 of file BPSecLib_Private.h.

BSL_HOSTEID_INIT_INVALID [1/2]

#define BSL_HOSTEID_INIT_INVALID   { .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.

Definition at line 390 of file BPSecLib_Private.h.

BSL_HOSTEID_INIT_INVALID [2/2]

#define BSL_HOSTEID_INIT_INVALID   { .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.

Definition at line 390 of file BPSecLib_Private.h.

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.

Definition at line 197 of file BPSecLib_Private.h.

BSL_LOG_DEBUG

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

Definition at line 205 of file BPSecLib_Private.h.

BSL_LOG_ERR

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

Definition at line 199 of file BPSecLib_Private.h.

BSL_LOG_INFO

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

Definition at line 203 of file BPSecLib_Private.h.

BSL_LOG_WARNING

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

Definition at line 201 of file BPSecLib_Private.h.

BSL_SecBlockType_IsSecBlock

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

Definition at line 596 of file BPSecLib_Private.h.

BSL_SECROLE_ISVALID

#define BSL_SECROLE_ISVALID

(

role_value

)

(((role_value) >= BSL_SECROLE_SOURCE) && ((role_value) <= BSL_SECROLE_ACCEPTOR))

Definition at line 583 of file BPSecLib_Private.h.

CHK_ARG_EXPR

#define CHK_ARG_EXPR

(

expr

)

CHK_TEMPL(expr, "Illegal Argument: Argument expression check failed to satisfy", BSL_ERR_ARG_INVALID)

Definition at line 225 of file BPSecLib_Private.h.

CHK_ARG_NONNULL

#define CHK_ARG_NONNULL

(

var

)

CHK_TEMPL((var) != NULL, "Illegal Argument: Argument null check failed to satisfy", BSL_ERR_ARG_NULL)

Definition at line 228 of file BPSecLib_Private.h.

CHK_AS_BOOL

#define CHK_AS_BOOL

(

expr

)

CHK_TEMPL(expr, "Failed Property Check: Failed to satisfy", BSL_ERR_ARG_INVALID)

Definition at line 223 of file BPSecLib_Private.h.

CHK_POSTCONDITION

#define CHK_POSTCONDITION

(

expr

)

CHK_TEMPL(expr, "Postcondition Failed: Did not satisfy", BSL_ERR_FAILURE);

Definition at line 235 of file BPSecLib_Private.h.

CHK_PRECONDITION

#define CHK_PRECONDITION

(

expr

)

CHK_TEMPL(expr, "Precondition Failed: Did not satisfy", BSL_ERR_FAILURE);

Definition at line 231 of file BPSecLib_Private.h.

CHK_PROPERTY

#define CHK_PROPERTY

(

expr

)

CHK_TEMPL(expr, "Property Failed: Did not satisfy", BSL_ERR_FAILURE);

Definition at line 233 of file BPSecLib_Private.h.

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.

Definition at line 211 of file BPSecLib_Private.h.

CHKERR1

#define CHKERR1

(

cond

)

CHKRET(cond, 1)

Return the error value 1 if condition fails.

Definition at line 135 of file BPSecLib_Private.h.

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.

Definition at line 141 of file BPSecLib_Private.h.

CHKFALSE

#define CHKFALSE

(

cond

)

CHKRET(cond, false)

Return false if condition fails.

Definition at line 133 of file BPSecLib_Private.h.

CHKNULL

#define CHKNULL

(

cond

)

CHKRET(cond, NULL)

Return a null pointer if condition fails.

Definition at line 131 of file BPSecLib_Private.h.

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 conditition to check.
val	The return value if the check fails.

Deprecated:

Definition at line 123 of file BPSecLib_Private.h.

CHKVOID

#define CHKVOID

(

cond

)

CHKRET(cond, )

Return from void functions if condition fails.

Definition at line 129 of file BPSecLib_Private.h.

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.

Definition at line 112 of file BPSecLib_Private.h.

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.

Definition at line 111 of file BPSecLib_Private.h.

Typedef Documentation

BSL_AbsSecBlock_t

typedef struct BSL_AbsSecBlock_s BSL_AbsSecBlock_t

Forward declaration of BSL_AbsSecBlock_t.

Definition at line 819 of file BPSecLib_Private.h.

BSL_DataConstPtr_t

typedef const uint8_t* BSL_DataConstPtr_t

Pointer to constant data for BSL_Data_t.

Definition at line 262 of file BPSecLib_Private.h.

BSL_DataPtr_t

typedef uint8_t* BSL_DataPtr_t

Data pointer for BSL_Data_t.

Definition at line 260 of file BPSecLib_Private.h.

BSL_PolicyDeinit_f

typedef void(* BSL_PolicyDeinit_f) (void *user_data)

Callback interface for policy provider to shut down and release any resources.

Definition at line 1110 of file BPSecLib_Private.h.

BSL_PolicyInspect_f

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.

Definition at line 1106 of file BPSecLib_Private.h.

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.

Definition at line 1154 of file BPSecLib_Private.h.

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.

Definition at line 1144 of file BPSecLib_Private.h.

BSL_SecOper_t

typedef struct BSL_SecOper_s BSL_SecOper_t

Represents a Security Operation produced by a policy provider to inform the security context.

Definition at line 731 of file BPSecLib_Private.h.

BSL_SecOutcome_t

typedef struct BSL_SecOutcome_s BSL_SecOutcome_t

Represents the output following execution of a security operation.

Definition at line 925 of file BPSecLib_Private.h.

BSL_SecParam_t

typedef struct BSL_SecParam_s BSL_SecParam_t

Represents a security parameter in an ASB as defined in RFC9172.

In an encoded ASB, these are tuples of (param-id, param-val)

Definition at line 661 of file BPSecLib_Private.h.

BSL_SecResult_t

typedef struct BSL_SecResult_s BSL_SecResult_t

Represents a security result, being a 2-tuple of (result-id, bytes).

Definition at line 600 of file BPSecLib_Private.h.

BSL_SeqReader_t

typedef struct BSL_SeqReader BSL_SeqReader_t

Forward declaration for file-like sequential reader.

Definition at line 348 of file BPSecLib_Private.h.

BSL_SeqWriter_t

typedef struct BSL_SeqWriter BSL_SeqWriter_t

Forward-declaration for file-like interface for a sequential writer.

Definition at line 368 of file BPSecLib_Private.h.

Enumeration Type Documentation

BSL_BundleASBFlag_e

enum BSL_BundleASBFlag_e

Flags of the Abstract Security Block [1].

Enumerator
BSL_ASB_FLAG_PARAMS	Flag set when parameters are present.

Definition at line 490 of file BPSecLib_Private.h.

BSL_BundleBlockTypeCode_e

enum BSL_BundleBlockTypeCode_e

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

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

Definition at line 476 of file BPSecLib_Private.h.

BSL_BundleCtrlFlag_e

enum BSL_BundleCtrlFlag_e

Bundle processing control flags.

Defined in Section 4.2.3 of RFC 9171 [3].

Enumerator
BSL_BUNDLE_IS_FRAGMENT	Set if this bundle is a fragment.

Definition at line 510 of file BPSecLib_Private.h.

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 an HMAC signature did not match.

Definition at line 52 of file BPSecLib_Private.h.

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.

Definition at line 146 of file BPSecLib_Private.h.

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.

Definition at line 589 of file BPSecLib_Private.h.

BSL_SecParam_InternalIds

enum BSL_SecParam_InternalIds

Defines supplementary Security Paramter 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_INT_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.

Definition at line 636 of file BPSecLib_Private.h.

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

Definition at line 625 of file BPSecLib_Private.h.

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.

Definition at line 576 of file BPSecLib_Private.h.

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

self	This security block
param	Non-Null Security parameter pointer to add to list

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

self	This security block
result	Non-Null Security result pointer to add to list

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

self	This ASB.
target_block_id	ID of a block, 0 indicates primary block as usual.

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

self	This ASB.
target_block_num	ID of a block, 0 indicates primary block

Referenced by BSL_API_QuerySecurity().

BSL_AbsSecBlock_DecodeFromCBOR()

int BSL_AbsSecBlock_DecodeFromCBOR	(	BSL_AbsSecBlock_t *	self,
		BSL_Data_t	encoded_cbor
	)

Decodes and populates this ASB from a CBOR string.

Parameters

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

Returns

Negative on error

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

self

This ASB

Referenced by BSL_API_QuerySecurity().

BSL_AbsSecBlock_EncodeToCBOR()

int BSL_AbsSecBlock_EncodeToCBOR	(	const BSL_AbsSecBlock_t *	self,
		BSL_Data_t	allocated_target
	)

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

Parameters

self	This ASB.
allocated_target	A buffer with allocated space for the encoded CBOR

Returns

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

BSL_AbsSecBlock_Init()

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

Populate a pre-allocated Absract Security Block.

Todo:

• Can be backend-only.

Parameters

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

BSL_AbsSecBlock_InitEmpty()

void BSL_AbsSecBlock_InitEmpty

(

BSL_AbsSecBlock_t *

self

)

Initialize a pre-allocated ASB with no contents.

Parameters

self

This ASB

BSL_AbsSecBlock_IsConsistent()

bool BSL_AbsSecBlock_IsConsistent

(

const BSL_AbsSecBlock_t *

self

)

Checks internal consistency and sanity of this structure.

Parameters

self

This ASB

Referenced by 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 tarets, params and results)

Parameters

self

This ASB.

BSL_AbsSecBlock_Print()

void BSL_AbsSecBlock_Print

(

const BSL_AbsSecBlock_t *

self

)

Prints to LOG INFO.

Todo:

• Can be backend-only.

Parameters

self

This ASB

Todo:

Refactor to dump this to a pre-allocated string.

BSL_AbsSecBlock_Sizeof()

size_t BSL_AbsSecBlock_Sizeof

(

void

)

Returns the size of the AbsSecBlock struct in bytes.

Returns

size of AbsSecBlock 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

self	This ASB
outcome	Security Operation outcome containing params and results

Returns

Negative on error, otherwise count of things removed.

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

Definition at line 96 of file HostInterface.c.

References BSL_HostDescriptors_t::block_create_fn, BSL_ERR_HOST_CALLBACK_FAILED, and BSL_SUCCESS.

BSL_BundleCtx_GetBlockIds()

int BSL_BundleCtx_GetBlockIds	(	const BSL_BundleRef_t *	bundle,
		size_t	array_count,
		uint64_t	block_ids_array[array_count],
		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

Definition at line 82 of file HostInterface.c.

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.

Definition at line 69 of file HostInterface.c.

References BSL_HostDescriptors_t::block_metadata_fn, BSL_ERR_HOST_CALLBACK_FAILED, and BSL_SUCCESS.

Referenced by BSL_API_QuerySecurity().

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

Definition at line 57 of file HostInterface.c.

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.

Definition at line 117 of file HostInterface.c.

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.

Definition at line 108 of file HostInterface.c.

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

Definition at line 195 of file LoggingStderr.c.

References event_queue, BSL_LogEvent_event_t::message, BSL_LogEvent_event_t::severity, thr_sink, thr_valid, and write_log().

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.
	len	The total length to allocate, which may be non-zero.
	src	An optional source buffer to copy from, from which len bytes will be copied.

Returns

Zero upon success.

Definition at line 164 of file UtilDefs_Data.c.

References BSL_Data_Resize(), BSL_LOG_ERR, BSL_SUCCESS, BSL_Data_s::len, and BSL_Data_s::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.
	len	The total length to allocate, which may be non-zero.
	src	An optional source buffer to copy from, from which len bytes will be copied.

Returns

Zero upon success.

Definition at line 100 of file UtilDefs_Data.c.

References BSL_Data_Resize(), BSL_LOG_ERR, BSL_SUCCESS, BSL_Data_s::owned, and BSL_Data_s::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.

Definition at line 92 of file UtilDefs_Data.c.

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

Definition at line 50 of file UtilDefs_Data.c.

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.
	bytelen	Length of buffer to allocate.

Returns

Zero upon success.

Definition at line 57 of file UtilDefs_Data.c.

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

Referenced by BSL_SecOutcome_Init().

BSL_Data_InitMove()

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.

Definition at line 84 of file UtilDefs_Data.c.

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.
	len	The total length to allocate, which may be zero.
	src	An optional source buffer to point to.

Returns

Zero upon success.

Definition at line 72 of file UtilDefs_Data.c.

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

Referenced by 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.
	len	The new total size.

Returns

Zero upon success.

Definition at line 131 of file UtilDefs_Data.c.

References BSL_ERR_INSUFFICIENT_SPACE, BSL_LOG_ERR, BSL_SUCCESS, BSL_Data_s::len, BSL_Data_s::owned, BSL_Data_s::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

Definition at line 147 of file HostInterface.c.

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

Definition at line 161 of file HostInterface.c.

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

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.

Definition at line 171 of file HostInterface.c.

References BSL_HostDescriptors_t::eid_from_text, 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.

Definition at line 140 of file HostInterface.c.

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

BSL_HostEID_EncodeToCBOR()

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

Encode a EID into a CBOR sequence.

Definition at line 154 of file HostInterface.c.

References BSL_HostDescriptors_t::eid_to_cbor.

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.

Definition at line 133 of file HostInterface.c.

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

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.

Definition at line 196 of file HostInterface.c.

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.

Definition at line 190 of file HostInterface.c.

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.

Definition at line 183 of file HostInterface.c.

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.

Definition at line 205 of file HostInterface.c.

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 bytestream 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 bytestream to be printed.
srclen	The length in bytes of srcbuf.

Returns

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

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

Definition at line 101 of file LoggingStderr.c.

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.

Definition at line 220 of file LoggingStderr.c.

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

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

Definition at line 175 of file LoggingStderr.c.

References BSL_LOG_QUEUE_SIZE, event_queue, BSL_LogEvent_event_t::message, BSL_LogEvent_event_t::severity, thr_sink, thr_valid, work_sink(), and write_log().

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]	self	This policy provider.
[out]	output_action_set	[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

A policy action set, which may contain error codes and other info

Definition at line 31 of file PolicyProvider.c.

References BSL_PolicyDesc_s::query_fn.

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

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

Definition at line 473 of file SecurityContext.c.

References BSL_ERR_SECURITY_CONTEXT_PARTIAL_FAIL, BSL_LOG_ERR, BSL_SecOper_IsBIB(), BSL_SecOper_IsRoleSource(), BSL_SecurityActionSet_CountSecOpers(), BSL_SecurityActionSet_GetSecOperAtIndex(), BSL_SecurityActionSet_IsConsistent(), BSL_SecurityResponseSet_Init(), BSL_SUCCESS, BSL_SecOper_s::context_id, BSL_SecCtxDesc_s::execute, and BSL_SecurityResponseSet_s::results.

Referenced by BSL_API_ApplySecurity().

BSL_SecCtx_ValidatePolicyActionSet()

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

Todo:

Doxygen

Definition at line 540 of file SecurityContext.c.

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

self	This security operation
param	Security parameter to include.

Definition at line 81 of file SecOperation.c.

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.

Definition at line 59 of file SecOperation.c.

References BSL_SecOper_IsConsistent().

Referenced by BSLX_BIB_InitFromSecOper().

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

self	Non-NULL pointer to this security operation

Definition at line 52 of file SecOperation.c.

References BSL_SecOper_IsConsistent().

Referenced by BSL_SecurityActionSet_Deinit().

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

Todo:

Clarify behavior if index is out of range.

Parameters

self	This security operation
index	Index of security paramter list to retrieve from

Returns

Pointer to security parameter type at given index.

Definition at line 105 of file SecOperation.c.

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

self	This security operation

Definition at line 91 of file SecOperation.c.

References BSL_SecOper_IsConsistent(), and BSL_SecOper_s::sec_block_num.

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

self	This security operation

Definition at line 98 of file SecOperation.c.

References BSL_SecOper_IsConsistent(), and BSL_SecOper_s::target_block_num.

BSL_SecOper_Init()

void BSL_SecOper_Init	(	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 a pre-allocated Security Operation with the given values.

Parameters

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

Definition at line 35 of file SecOperation.c.

References BSL_SecOper_s::_role, BSL_SecOper_IsConsistent(), BSL_SecOper_s::context_id, BSL_SecOper_s::failure_code, BSL_SecOper_s::sec_block_num, and BSL_SecOper_s::target_block_num.

Referenced by BSLP_PolicyRule_EvaluateAsSecOper().

BSL_SecOper_IsBIB()

bool BSL_SecOper_IsBIB

(

const BSL_SecOper_t *

self

)

Return true if this security operation is BIB.

Parameters

self	This security operation

Returns

boolen

Definition at line 125 of file SecOperation.c.

References BSL_SECBLOCKTYPE_BIB.

Referenced by BSL_SecCtx_ExecutePolicyActionSet().

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

self	This security operation

Returns

True if consistent, may assert false otherwise.

Definition at line 66 of file SecOperation.c.

References BSL_SecOper_s::_role, BSL_SECBLOCKTYPE_BCB, BSL_SECBLOCKTYPE_BIB, BSL_SECROLE_ACCEPTOR, BSL_SECROLE_SOURCE, BSL_SECROLE_VERIFIER, BSL_SecOper_s::context_id, and BSL_SecOper_s::target_block_num.

Referenced by BSL_SecOper_AppendParam(), BSL_SecOper_CountParams(), BSL_SecOper_Deinit(), BSL_SecOper_GetParamAt(), BSL_SecOper_GetSecurityBlockNum(), BSL_SecOper_GetTargetBlockNum(), BSL_SecOper_Init(), BSL_SecOutcome_Init(), BSL_SecurityActionSet_AppendSecOper(), and BSL_SecurityActionSet_GetSecOperAtIndex().

BSL_SecOper_IsRoleAccepter()

bool BSL_SecOper_IsRoleAccepter

(

const BSL_SecOper_t *

self

)

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

Parameters

self	This Security Operation

Returns

boolean

Definition at line 119 of file SecOperation.c.

References BSL_SecOper_s::_role, 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

self	This Security Operation

Returns

boolean

Definition at line 113 of file SecOperation.c.

References BSL_SecOper_s::_role, and BSL_SECROLE_SOURCE.

Referenced by BSL_SecCtx_ExecutePolicyActionSet().

BSL_SecOper_IsRoleVerifier()

bool BSL_SecOper_IsRoleVerifier

(

const BSL_SecOper_t *

self

)

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

Parameters

self	This Security Operation

Returns

boolean

BSL_SecOper_Sizeof()

size_t BSL_SecOper_Sizeof

(

void

)

Definition at line 30 of file SecOperation.c.

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

self	Non-NULL pointer to this security outcome.
param	Non-NULL pointer to security parameter to copy and append.

Definition at line 131 of file SecOutcome.c.

References BSL_SecParam_IsConsistent(), and BSL_SecOutcome_s::param_list.

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

self	Non-NULL pointer to this security outcome.
sec_result	Non-NULL pointer to security result to copy and append.

Definition at line 90 of file SecOutcome.c.

References BSL_SecResult_IsConsistent(), and BSL_SecOutcome_s::result_list.

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

Definition at line 116 of file SecOutcome.c.

References BSL_SecOutcome_s::param_list.

BSL_SecOutcome_CountResults()

size_t BSL_SecOutcome_CountResults

(

const BSL_SecOutcome_t *

self

)

Get the number of results.

Parameters

self	this sec outcome

Definition at line 102 of file SecOutcome.c.

References BSL_SecOutcome_s::result_list.

BSL_SecOutcome_Deinit()

void BSL_SecOutcome_Deinit

(

BSL_SecOutcome_t *

self

)

Release any resources owned by this security outcome.

Parameters

self	Non-Null pointer to this security outcome.

Definition at line 55 of file SecOutcome.c.

References BSL_SecOutcome_s::allocation, BSL_Data_Deinit(), BSL_SecOutcome_s::param_list, and BSL_SecOutcome_s::result_list.

BSL_SecOutcome_GetParamAt()

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

Definition at line 123 of file SecOutcome.c.

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

self	This outcome
index	Index in the list to retrieve

Definition at line 108 of file SecOutcome.c.

References BSL_SecOutcome_s::result_list.

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

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

Definition at line 37 of file SecOutcome.c.

References BSL_SecOutcome_s::allocation, BSL_Data_InitBuffer(), BSL_SecOper_IsConsistent(), BSL_SecOutcome_s::is_success, BSL_SecOutcome_s::param_list, BSL_SecOutcome_s::result_list, and BSL_SecOutcome_s::sec_oper.

BSL_SecOutcome_IsConsistent()

bool BSL_SecOutcome_IsConsistent

(

const BSL_SecOutcome_t *

self

)

Return true if internal invariants hold.

Parameters

self	This sec outcome.

Returns

true if invariants hold

Definition at line 65 of file SecOutcome.c.

References BSL_SecOutcome_s::allocation, BSL_SecOutcome_s::is_success, BSL_Data_s::len, BSL_SecOutcome_s::param_list, BSL_Data_s::ptr, BSL_SecOutcome_s::result_list, and BSL_SecOutcome_s::sec_oper.

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

self
outcome

Returns

Definition at line 165 of file SecOutcome.c.

References BSL_AbsSecBlock_IsConsistent(), BSL_LOG_DEBUG, BSL_LOG_ERR, BSL_SecOutcome_s::result_list, and BSL_SecResult_s::target_block_num.

BSL_SecOutcome_Sizeof()

size_t BSL_SecOutcome_Sizeof

(

void

)

Returns the size of the BSL_SecOutcome_t structure.

Definition at line 32 of file SecOutcome.c.

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

self	This Security Parameter
result	Pointer to pre-allocated data into which the bytestring is copied.

Returns

Negative on error.

Definition at line 77 of file SecParam.c.

References BSL_SecParam_s::_bytelen, BSL_SecParam_s::_bytes, BSL_Data_InitView(), and BSL_SecParam_IsConsistent().

Referenced by 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

self	This Security Parameter

Returns

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

Definition at line 69 of file SecParam.c.

References BSL_SecParam_s::_type, BSL_SecParam_s::_uint_value, and BSL_SECPARAM_TYPE_INT64.

Referenced by 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

Definition at line 85 of file SecParam.c.

References BSL_SecParam_IsConsistent(), and BSL_SecParam_s::param_id.

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

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

Returns

Negative on an error.

Definition at line 34 of file SecParam.c.

References BSL_SecParam_s::_bytelen, BSL_SecParam_s::_bytes, BSL_SecParam_s::_type, BSL_SECPARAM_TYPE_BYTESTR, BSL_SUCCESS, BSL_Data_s::len, BSL_SecParam_s::param_id, and BSL_Data_s::ptr.

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

self	This Security Paramter
param_id	ID of the parameter
value	View of bytes, which get copied into this Security Parameter.

Returns

Negative on an error.

Definition at line 51 of file SecParam.c.

References BSL_SecParam_s::_type, BSL_SecParam_s::_uint_value, BSL_SECPARAM_TYPE_INT64, BSL_SUCCESS, and BSL_SecParam_s::param_id.

BSL_SecParam_IsConsistent()

bool BSL_SecParam_IsConsistent

(

const BSL_SecParam_t *

self

)

Return true if invariant conditions pass.

Parameters

self	This security parameter

Returns

true if valid, false otherwise.

Definition at line 92 of file SecParam.c.

References BSL_SecParam_s::_bytelen, BSL_SecParam_s::_bytes, BSL_SecParam_s::_type, BSL_SecParam_s::_uint_value, BSL_SECPARAM_TYPE_BYTESTR, BSL_SECPARAM_TYPE_INT64, BSL_SECPARAM_TYPE_UNKNOWN, and BSL_SecParam_s::param_id.

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

self	This Security Parameter

Returns

True when value type is integer.

Definition at line 63 of file SecParam.c.

References BSL_SecParam_s::_type, and BSL_SECPARAM_TYPE_INT64.

Referenced by 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 paramter.

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.

Definition at line 111 of file SecParam.c.

References BSL_SECPARAM_TYPE_INT_STARTINDEX.

BSL_SecParam_Sizeof()

size_t BSL_SecParam_Sizeof

(

void

)

Return size of BSL_SecParam_t struct type.

Definition at line 29 of file SecParam.c.

Referenced by BSLP_PolicyRule_AddParam(), BSLP_PolicyRule_EvaluateAsSecOper(), and BSLP_PolicyRule_Init().

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

Parameters

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

Definition at line 28 of file SecResult.c.

References BSL_SecResult_s::_bytelen, BSL_SecResult_s::_bytes, BSL_SecResult_IsConsistent(), BSL_SUCCESS, BSL_SecResult_s::context_id, BSL_Data_s::len, BSL_Data_s::ptr, BSL_SecResult_s::result_id, and BSL_SecResult_s::target_block_num.

BSL_SecResult_IsConsistent()

bool BSL_SecResult_IsConsistent

(

const BSL_SecResult_t *

self

)

Return true when internal invariant checks pass.

Parameters

self	This security result

Definition at line 47 of file SecResult.c.

References BSL_SecResult_s::_bytelen, BSL_SecResult_s::context_id, BSL_SecResult_s::result_id, and BSL_SecResult_s::target_block_num.

Referenced by BSL_SecOutcome_AppendResult(), and BSL_SecResult_Init().

BSL_SecResult_Sizeof()

size_t BSL_SecResult_Sizeof

(

void

)

Returns size in bytes of BSL_SecResult_t.

Definition at line 59 of file SecResult.c.

BSL_SecurityActionSet_AppendSecOper()

int BSL_SecurityActionSet_AppendSecOper	(	BSL_SecurityActionSet_t *	self,
		const BSL_SecOper_t *	sec_oper
	)

Append a security operation to the security action set.

Parameters

[in,out]	self	This security action set.
[in]	sec_oper	Security operation to include.

Returns

0 on success, negative on error

Definition at line 90 of file SecurityActionSet.c.

References BSL_SecurityActionSet_s::arrays_capacity, BSL_SecOper_IsConsistent(), BSL_SecurityActionSet_IsConsistent(), BSL_SUCCESS, BSL_SecurityActionSet_s::sec_operations, and BSL_SecurityActionSet_s::sec_operations_count.

Referenced by BSLP_QueryPolicy().

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 ot this security action set.

Returns

Count of errors.

Definition at line 72 of file SecurityActionSet.c.

References BSL_SecurityActionSet_IsConsistent(), and BSL_SecurityActionSet_s::err_code.

Referenced by BSLP_QueryPolicy().

BSL_SecurityActionSet_CountSecOpers()

size_t BSL_SecurityActionSet_CountSecOpers

(

const BSL_SecurityActionSet_t *

self

)

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

Parameters

self	This action set.

Returns

Number of operations, 0 indicates no policy matched.

Definition at line 102 of file SecurityActionSet.c.

References BSL_SecurityActionSet_IsConsistent(), and BSL_SecurityActionSet_s::sec_operations_count.

Referenced by BSL_SecCtx_ExecutePolicyActionSet(), and BSL_SecurityActionSet_GetSecOperAtIndex().

BSL_SecurityActionSet_Deinit()

void BSL_SecurityActionSet_Deinit

(

BSL_SecurityActionSet_t *

self

)

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

Parameters

self	This action set.

Definition at line 79 of file SecurityActionSet.c.

References BSL_SecurityActionSet_s::arrays_capacity, BSL_SecOper_Deinit(), BSL_SecurityActionSet_IsConsistent(), and BSL_SecurityActionSet_s::sec_operations.

BSL_SecurityActionSet_GetErrCode()

int BSL_SecurityActionSet_GetErrCode

(

const BSL_SecurityActionSet_t *

self

)

Get the error code after querying (inspecting) policy actions.

Non-zero indicates error

Parameters

[in]

self

this action set

Returns

Anomaly on non-zero

Definition at line 121 of file SecurityActionSet.c.

References BSL_SecurityActionSet_IsConsistent(), and BSL_SecurityActionSet_s::err_code.

BSL_SecurityActionSet_GetSecOperAtIndex()

const BSL_SecOper_t * BSL_SecurityActionSet_GetSecOperAtIndex	(	const BSL_SecurityActionSet_t *	self,
		size_t	index
	)

Returns the Security Operation at the given index.

Parameters

self	This action set
index	index

Returns

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

Definition at line 108 of file SecurityActionSet.c.

References BSL_SecOper_IsConsistent(), BSL_SecurityActionSet_CountSecOpers(), BSL_SecurityActionSet_IsConsistent(), and BSL_SecurityActionSet_s::sec_operations.

Referenced by BSL_SecCtx_ExecutePolicyActionSet().

BSL_SecurityActionSet_IncrError()

void BSL_SecurityActionSet_IncrError

(

BSL_SecurityActionSet_t *

self

)

Increment a security failure for this action set.

Parameters

[in,out]

self

Pointer to this security action set.

Definition at line 66 of file SecurityActionSet.c.

References BSL_SecurityActionSet_IsConsistent(), and BSL_SecurityActionSet_s::err_code.

Referenced by BSLP_QueryPolicy().

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

Definition at line 56 of file SecurityActionSet.c.

References BSL_SecurityActionSet_s::arrays_capacity, BSL_SecurityActionSet_IsConsistent(), and BSL_SecurityActionSet_s::sec_operations.

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.

Definition at line 28 of file SecurityActionSet.c.

References BSL_SecurityActionSet_s::arrays_capacity, BSL_SecurityActionSet_s::new_block_ids, BSL_SecurityActionSet_s::new_block_types, BSL_SecurityActionSet_s::sec_operations, and BSL_SecurityActionSet_s::sec_operations_count.

Referenced by BSL_SecCtx_ExecutePolicyActionSet(), BSL_SecurityActionSet_AppendSecOper(), BSL_SecurityActionSet_CountErrors(), BSL_SecurityActionSet_CountSecOpers(), BSL_SecurityActionSet_Deinit(), BSL_SecurityActionSet_GetErrCode(), BSL_SecurityActionSet_GetSecOperAtIndex(), BSL_SecurityActionSet_IncrError(), BSL_SecurityActionSet_Init(), 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

Definition at line 51 of file SecurityActionSet.c.

Referenced by BSLP_QueryPolicy().

BSL_SecurityResponseSet_CountResponses()

size_t BSL_SecurityResponseSet_CountResponses

(

const BSL_SecurityResponseSet_t *

self

)

Return number of responses (operations acted upon)

Parameters

self	This response set.

Definition at line 55 of file SecurityResultSet.c.

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.

Definition at line 49 of file SecurityResultSet.c.

References BSL_SecurityResponseSet_IsConsistent().

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

Todo:

This is still undefined.

Definition at line 41 of file SecurityResultSet.c.

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.

Definition at line 33 of file SecurityResultSet.c.

Referenced by BSL_SecurityResponseSet_CountResponses(), and BSL_SecurityResponseSet_Deinit().

BSL_SecurityResponseSet_Sizeof()

size_t BSL_SecurityResponseSet_Sizeof

(

void

)

Returns size of this struct type.

Definition at line 28 of file SecurityResultSet.c.

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.

Definition at line 36 of file UtilDefs_SeqReadWrite.c.

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

	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.

Definition at line 54 of file UtilDefs_SeqReadWrite.c.

References BSL_SUCCESS, BSL_SeqReader::cursor, and BSL_SeqReader::remain.

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.

Definition at line 84 of file UtilDefs_SeqReadWrite.c.

References BSL_SUCCESS, and BSL_SeqWriter::fd.

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.

Definition at line 95 of file UtilDefs_SeqReadWrite.c.

References BSL_SUCCESS, and BSL_SeqWriter::fd.

Referenced by BSL_Cipher_AddSeq(), and BSL_Cipher_FinalizeSeq().