Defines a security operation. More...

#include "SecOperation.h"
#include "SecParam.h"

Include dependency graph for SecOperation.c:

Functions
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, int64_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 policy_action)
	Populate an initialized Security Operation with the given values.

size_t	BSL_SecOper_CountParams (const BSL_SecOper_t *self)
	Get the count of parameters contained within this security operation.

bool	BSL_SecOper_IsConsistent (const BSL_SecOper_t *self)
	Returns true if internal consistency and sanity checks pass.

void	BSL_SecOper_AppendParam (BSL_SecOper_t self, const BSL_SecParam_t param)
	Add the given security parameter to this list of 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.

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.

bool	BSL_SecOper_IsRoleSource (const BSL_SecOper_t *self)
	Return true if this security operation's role is SOURCE.

bool	BSL_SecOper_IsRoleAcceptor (const BSL_SecOper_t *self)
	Return true if this security operation's role is Acceptor.

bool	BSL_SecOper_IsRoleVerifier (const BSL_SecOper_t *self)
	Return true if this security operation's role is Verifier.

bool	BSL_SecOper_IsBIB (const BSL_SecOper_t *self)
	Return true if this security operation is BIB.

BSL_PolicyAction_e	BSL_SecOper_GetPolicyAction (const BSL_SecOper_t *self)
	Retrieve the policy action of a security operation.

BSL_ReasonCode_t	BSL_SecOper_GetReasonCode (const BSL_SecOper_t *self)
	Get security operation reason code.

void	BSL_SecOper_SetReasonCode (BSL_SecOper_t *self, BSL_ReasonCode_t new_reason_code)
	Set the security operation reason code.

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.

Detailed Description

Defines a security operation.

Function Documentation

◆ 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 ASSERT_ARG_EXPR, ASSERT_POSTCONDITION, ASSERT_PRECONDITION, BSL_SecOper_IsConsistent(), and BSL_SecParam_IsConsistent().

Referenced by BSL_TestUtils_InitBCB_Appendix2(), BSL_TestUtils_InitBIB_AppendixA1(), BSLP_PolicyRule_EvaluateAsSecOper(), test_RFC9173_AppendixA_Example3_Acceptor(), test_RFC9173_AppendixA_Example3_Source(), test_RFC9173_AppendixA_Example4_Acceptor(), test_RFC9173_AppendixA_Example4_Source(), test_sec_accept_keyunwrap(), and test_sec_source_keywrap().

◆ 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 ASSERT_PRECONDITION, and BSL_SecOper_IsConsistent().

Referenced by BSLX_BCB_GetParams(), BSLX_BIB_Execute(), 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 ASSERT_ARG_NONNULL.

Referenced by BCBTestContext_Deinit(), BIBTestContext_Deinit(), and BSLP_QueryPolicy().

◆ 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 ASSERT_PRECONDITION, and BSL_SecOper_IsConsistent().

Referenced by BSL_API_ApplySecurity(), BSLP_FinalizePolicy(), test_BSL_32(), TEST_CASE(), and test_dyn_mem_cbs_BSL_32().

◆ 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 ASSERT_PRECONDITION, and BSL_SecOper_IsConsistent().

Referenced by BSLX_BCB_GetParams(), BSLX_BIB_Execute(), and BSLX_BIB_InitFromSecOper().

◆ BSL_SecOper_GetPolicyAction()

BSL_PolicyAction_e BSL_SecOper_GetPolicyAction ( const BSL_SecOper_t * self )

Retrieve the policy action of a security operation.

Parameters

[in] self The security operation

Returns: the policy action

References ASSERT_PRECONDITION, and BSL_SecOper_IsConsistent().

Referenced by BSLP_PolicyProvider_HandleFailures().

◆ BSL_SecOper_GetReasonCode()

BSL_ReasonCode_t BSL_SecOper_GetReasonCode ( const BSL_SecOper_t * self )

Get security operation reason code.

Parameters

[in] self the security operation

Returns: the reason code of the security operation

References ASSERT_PRECONDITION, and BSL_SecOper_IsConsistent().

Referenced by BSL_SecCtx_ExecutePolicyActionSet(), and BSLP_PolicyProvider_HandleFailures().

◆ 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 ASSERT_PRECONDITION, and BSL_SecOper_IsConsistent().

Referenced by BSLP_QueryPolicy(), BSLX_BCB_Execute(), BSLX_BCB_GetParams(), and BSLX_BIB_Execute().

◆ 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 ASSERT_PRECONDITION, and BSL_SecOper_IsConsistent().

Referenced by BSL_ExecBCBAcceptor(), BSL_ExecBIBAccept(), BSLP_PolicyProvider_HandleFailures(), BSLP_QueryPolicy(), BSLX_BCB_Execute(), BSLX_BCB_Init(), and BSLX_BIB_Execute().

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

Referenced by BCBTestContext_Init(), BIBTestContext_Init(), BSL_TestUtils_InitMallocBIBActionSet(), BSLP_QueryPolicy(), test_RFC9173_AppendixA_Example3_Acceptor(), test_RFC9173_AppendixA_Example3_Source(), test_RFC9173_AppendixA_Example4_Acceptor(), test_RFC9173_AppendixA_Example4_Source(), 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 ASSERT_ARG_NONNULL, ASSERT_POSTCONDITION, and 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 ASSERT_PRECONDITION, 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, BSL_SECROLE_VERIFIER, and CHK_AS_BOOL.

Referenced by BSL_ExecBIBAccept(), BSL_SecOper_AppendParam(), BSL_SecOper_CountParams(), BSL_SecOper_GetConclusion(), BSL_SecOper_GetParamAt(), BSL_SecOper_GetPolicyAction(), BSL_SecOper_GetReasonCode(), BSL_SecOper_GetSecurityBlockNum(), BSL_SecOper_GetTargetBlockNum(), BSL_SecOper_InitSet(), BSL_SecOper_IsBIB(), BSL_SecOper_IsRoleAcceptor(), BSL_SecOper_IsRoleSource(), BSL_SecOper_IsRoleVerifier(), BSL_SecOper_Populate(), BSL_SecOper_Set(), BSL_SecOper_SetConclusion(), BSL_SecOper_SetReasonCode(), BSL_SecOutcome_Init(), and BSLX_BIB_Execute().

◆ 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 ASSERT_PRECONDITION, BSL_SecOper_IsConsistent(), and BSL_SECROLE_ACCEPTOR.

Referenced by BSL_ExecBCBAcceptor(), and BSL_ExecBIBAccept().

◆ 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 ASSERT_PRECONDITION, BSL_SecOper_IsConsistent(), and BSL_SECROLE_SOURCE.

Referenced by BSL_SecCtx_ExecutePolicyActionSet(), BSLP_QueryPolicy(), BSLX_BCB_Execute(), BSLX_BCB_Init(), and BSLX_BIB_InitFromSecOper().

◆ 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 ASSERT_PRECONDITION, BSL_SecOper_IsConsistent(), and BSL_SECROLE_VERIFIER.

◆ BSL_SecOper_Populate()

void BSL_SecOper_Populate	(	BSL_SecOper_t *	self,
		int64_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	policy_action
	)

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.
[in]	policy_action	Member of BSL_PolicyAction_e enum indicating failure policy