Security Actions & Security Operation Handling

docs/api/dictionary.txt

@@ -46,6 +46,8 @@ bytestream
 bytestring
 bytestrings
 callee's
+calloc
+CALLOC
 Carsten
 CBOR
 cek
@@ -169,6 +171,11 @@ RTEMS
 ruleset
 sc
 SCs
+SecOper
+SecParam
+SecResult
+SecurityAction
+SecurityActionSet
 SHA
 sipos
 speciality

mock-bpa-test/requirements_tests.py

@@ -45,7 +45,7 @@ def __init__(self):
                 [7, 0, 0, [2, [1, 2]], [2, [2, 1]], [2, [2, 1]], [0, 40], 1000000],
                 [1, 1, 0, 0, bytes.fromhex('526561647920746F2067656E657261746520612033322D62797465207061796C6F6164')]
             ],
-            policy_config='0x186,0x187',
+            policy_config='0x1A6,0x1A7',
             is_implemented=True,
             is_working=True,
             expect_success=True,

src/BPSecLib_Private.h

@@ -774,17 +774,18 @@ typedef struct BSL_SecOper_s BSL_SecOper_t;
 
 size_t BSL_SecOper_Sizeof(void);
 
-/** Populate a pre-allocated Security Operation with the given values.
+/** Initialize a newly allocated structure.
  *
- * @param[in,out] self Non-NULL pointer to this security operation.
- * @param[in] context_id ID of the security context
- * @param[in] target_block_num Block ID of security target block
- * @param[in] sec_block_num Block ID of security block.
- * @param[in] sec_type Member of ::BSL_SecBlockType_e enum indicating BIB or BCB
- * @param[in] sec_role Member of ::BSL_SecRole_e enum indicating role.
+ * @param[in,out] self Non-NULL pointer to this security operation
+ */
+void BSL_SecOper_Init(BSL_SecOper_t *self);
+
+/** Initialize from a copy.
+ *
+ * @param[in,out] self Non-NULL pointer to this security operation
+ * @param[in] src Non-NULL pointer to this source to copy from.
  */
-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);
+void BSL_SecOper_InitSet(BSL_SecOper_t *self, const BSL_SecOper_t *src);
 
 /** Empty and release any resources used internally by this structure.
  *
@@ -795,6 +796,25 @@ void BSL_SecOper_Init(BSL_SecOper_t *self, uint64_t context_id, uint64_t target_
  */
 void BSL_SecOper_Deinit(BSL_SecOper_t *self);
 
+/** Set from a copy.
+ *
+ * @param[in,out] self Non-NULL pointer to this security operation
+ * @param[in] src Non-NULL pointer to this source to copy from.
+ */
+void BSL_SecOper_Set(BSL_SecOper_t *self, const BSL_SecOper_t *src);
+
+/** Populate an initialized Security Operation with the given values.
+ *
+ * @param[in,out] self Non-NULL pointer to this security operation.
+ * @param[in] context_id ID of the security context
+ * @param[in] target_block_num Block ID of security target block
+ * @param[in] sec_block_num Block ID of security block.
+ * @param[in] sec_type Member of ::BSL_SecBlockType_e enum indicating BIB or BCB
+ * @param[in] sec_role Member of ::BSL_SecRole_e enum indicating role.
+ */
+void BSL_SecOper_Populate(BSL_SecOper_t *self, uint64_t context_id, uint64_t target_block_num, uint64_t sec_block_num,
+                          BSL_SecBlockType_e sec_type, BSL_SecRole_e sec_role, BSL_PolicyAction_e failure_code);
+
 /** Returns true if internal consistency and sanity checks pass
  *
  * @todo Formalize invariants
@@ -857,6 +877,20 @@ bool BSL_SecOper_IsRoleAcceptor(const BSL_SecOper_t *self);
  */
 bool BSL_SecOper_IsBIB(const BSL_SecOper_t *self);
 
+/**
+ * Retrieve the conclusion state of a security operation
+ * @param[in] self The security operation
+ * @return the conclusion state
+ */
+BSL_SecOper_ConclusionState_e BSL_SecOper_GetConclusion(const BSL_SecOper_t *self);
+
+/**
+ * Set the security operation conclusion state
+ * @param[in,out] self security operation to change conclusion state of
+ * @param[in] new_conclusion new conclusion to set to
+ */
+void BSL_SecOper_SetConclusion(BSL_SecOper_t *self, BSL_SecOper_ConclusionState_e new_conclusion);
+
 /// Forward declaration of this struct
 typedef struct BSL_AbsSecBlock_s BSL_AbsSecBlock_t;
 
@@ -1032,6 +1066,11 @@ void BSL_SecOutcome_AppendParam(BSL_SecOutcome_t *self, const BSL_SecParam_t *pa
  */
 size_t BSL_SecOutcome_CountParams(const BSL_SecOutcome_t *self);
 
+/** Get the security parameter from the security outcome at the provided index
+ * @param[in] self security outcome
+ * @param[in] index index to retrieve security parameter from
+ * @return Security parameter
+ */
 const BSL_SecParam_t *BSL_SecOutcome_GetParamAt(const BSL_SecOutcome_t *self, size_t index);
 
 /// @brief Returns true if this (the parameters and results) is contained within the given ASK
@@ -1041,28 +1080,80 @@ const BSL_SecParam_t *BSL_SecOutcome_GetParamAt(const BSL_SecOutcome_t *self, si
 /// @return
 bool BSL_SecOutcome_IsInAbsSecBlock(const BSL_SecOutcome_t *self, const BSL_AbsSecBlock_t *abs_sec_block);
 
-/// @brief Returns size of the struct, helpful for dynamic allocation.
-/// @return Size of the struct
-size_t BSL_SecurityActionSet_Sizeof(void);
+/**
+ * @return size of security operation
+ */
+size_t BSL_SecurityAction_Sizeof(void);
 
-/** @brief Initialize a new security action set
+/**
+ * @return true if security action @param self is consistent
+ */
+bool BSL_SecurityAction_IsConsistent(const BSL_SecurityAction_t *self);
+
+/**
+ * Initialize security action
+ * @param[out] self security action
+ */
+void BSL_SecurityAction_Init(BSL_SecurityAction_t *self);
+
+/** Initialize from a copy.
  *
- * @param[in,out] self This pre-allocated action set
+ * @param[out] self security action
+ * @param[in] src The source of the copy.
  */
-void BSL_SecurityActionSet_Init(BSL_SecurityActionSet_t *self);
+void BSL_SecurityAction_InitSet(BSL_SecurityAction_t *self, const BSL_SecurityAction_t *src);
+
+/**
+ * De-initialize security action
+ * @param[in,out] self security action
+ */
+void BSL_SecurityAction_Deinit(BSL_SecurityAction_t *self);
+
+/**
+ * Add security operation to security action, with deterministic ordering
+ * @param[in,out] self action to add security operation to
+ * @param[in,out] sec_oper new security operation to add and move from.
+ * @return 0 if successful
+ */
+int BSL_SecurityAction_AppendSecOper(BSL_SecurityAction_t *self, BSL_SecOper_t *sec_oper);
+
+/** Order the Security operations such that execution will be successful
+ * @param[in, out] self action to sort
+ */
+int BSL_SecurityAction_OrderSecOps(BSL_SecurityAction_t *self);
+
+/**
+ * @return number of security operation in the @param[in] self action
+ */
+size_t BSL_SecurityAction_CountSecOpers(const BSL_SecurityAction_t *self);
+
+/**
+ * @return the security operation at @param[in] index index in @param[in] self security action
+ */
+BSL_SecOper_t *BSL_SecurityAction_GetSecOperAtIndex(const BSL_SecurityAction_t *self, size_t index);
 
 /** @brief Increment a security failure for this action set
  *
  * @param[in,out] self Pointer to this security action set.
  */
-void BSL_SecurityActionSet_IncrError(BSL_SecurityActionSet_t *self);
+void BSL_SecurityAction_IncrError(BSL_SecurityAction_t *self);
 
-/** @brief Returns count of failures after processing this action set
+/** @brief Returns count of failures after processing this action
  *
- * @param[in] self Pointer to this security action set.
+ * @param[in] self Pointer to this security action.
  * @return Count of errors.
  */
-size_t BSL_SecurityActionSet_CountErrors(const BSL_SecurityActionSet_t *self);
+size_t BSL_SecurityAction_CountErrors(const BSL_SecurityAction_t *self);
+
+/// @brief Returns size of the struct, helpful for dynamic allocation.
+/// @return Size of the struct
+size_t BSL_SecurityActionSet_Sizeof(void);
+
+/** @brief Initialize a new security action set
+ *
+ * @param[in,out] self This pre-allocated action set
+ */
+void BSL_SecurityActionSet_Init(BSL_SecurityActionSet_t *self);
 
 /** Zeroize, clear, and release itself and any owned resources.
  *
@@ -1073,10 +1164,10 @@ void BSL_SecurityActionSet_Deinit(BSL_SecurityActionSet_t *self);
 /** @brief Append a security operation to the security action set
  *
  * @param[in,out] self This security action set.
- * @param[in] sec_oper Security operation to include.
+ * @param[in] action Action to include.
  * @return 0 on success, negative on error
  */
-int BSL_SecurityActionSet_AppendSecOper(BSL_SecurityActionSet_t *self, const BSL_SecOper_t *sec_oper);
+int BSL_SecurityActionSet_AppendAction(BSL_SecurityActionSet_t *self, const BSL_SecurityAction_t *action);
 
 /** Return true if internal sanity and consistency checks pass
  *
@@ -1085,27 +1176,32 @@ int BSL_SecurityActionSet_AppendSecOper(BSL_SecurityActionSet_t *self, const BSL
  */
 bool BSL_SecurityActionSet_IsConsistent(const BSL_SecurityActionSet_t *self);
 
+/**
+ * @return the total number of operations within each of the actions of @param self action set
+ */
+size_t BSL_SecurityActionSet_CountOperations(const BSL_SecurityActionSet_t *self);
+
 /** Count number of security operations present in this policy action set.
  *
  * @param[in] self This action set.
- * @return Number of operations, 0 indicates no policy matched.
+ * @return Number of actions, 0 indicates no policy matched.
  */
-size_t BSL_SecurityActionSet_CountSecOpers(const BSL_SecurityActionSet_t *self);
+size_t BSL_SecurityActionSet_CountActions(const BSL_SecurityActionSet_t *self);
 
 /** Returns the Security Operation at the given index.
  *
  * @param[in] self This action set
  * @param[in] index index
- * @return pointer to security operation at given index, asserting false if not in bound
+ * @return pointer to action at given index, asserting false if not in bound
  */
-const BSL_SecOper_t *BSL_SecurityActionSet_GetSecOperAtIndex(const BSL_SecurityActionSet_t *self, size_t index);
+const BSL_SecurityAction_t *BSL_SecurityActionSet_GetActionAtIndex(const BSL_SecurityActionSet_t *self, size_t index);
 
-/** Get the error code after querying (inspecting) policy actions. Non-zero indicates error
+/** @brief Returns count of failures after processing this action set
  *
- * @param[in] self this action set
- * @return Anomaly on non-zero
+ * @param[in] self Pointer to this security action set.
+ * @return Count of errors.
  */
-int BSL_SecurityActionSet_GetErrCode(const BSL_SecurityActionSet_t *self);
+size_t BSL_SecurityActionSet_CountErrors(const BSL_SecurityActionSet_t *self);
 
 /// @brief Returns size of this struct type
 size_t BSL_SecurityResponseSet_Sizeof(void);
@@ -1232,4 +1328,4 @@ struct BSL_SecCtxDesc_s
     BSL_SecCtx_Execute_f execute;
 };
 
-#endif /* BSL_BPSECLIB_PRIVATE_H_ */
+#endif /* BSL_BPSECLIB_PRIVATE_H_ */

src/BPSecLib_Public.h

@@ -51,9 +51,13 @@ typedef struct BSL_LibCtx_s BSL_LibCtx_t;
 /// process the Bundle.
 typedef struct BSL_SecurityResponseSet_s BSL_SecurityResponseSet_t;
 
-/// @brief Forward declaration of ::BSL_SecurityActionSet_s, which contains information for BSL to process the Bundle.
+/// @brief Forward declaration of ::BSL_SecurityActionSet_s, which contains actions for BSL to process the Bundle.
 typedef struct BSL_SecurityActionSet_s BSL_SecurityActionSet_t;
 
+/// @brief Forward declaration of ::BSL_SecurityAction_s, which contains security operations for BSL to process the
+/// Bundle.
+typedef struct BSL_SecurityAction_s BSL_SecurityAction_t;
+
 /// @brief Forward-declaration for structure containing callbacks to a security context.
 typedef struct BSL_SecCtxDesc_s BSL_SecCtxDesc_t;
 
@@ -79,6 +83,21 @@ typedef enum
     BSL_POLICYLOCATION_CLOUT
 } BSL_PolicyLocation_e;
 
+/**
+ * @brief Indicates the conclusion state of a security operation
+ */
+typedef enum
+{
+    /// @brief Security operation is still pending action
+    BSL_SECOP_CONCLUSION_PENDING = 1,
+    /// @brief Security operation has concluded and succeeded
+    BSL_SECOP_CONCLUSION_SUCCESS,
+    /// @brief Security operation is invalid
+    BSL_SECOP_CONCLUSION_INVALID,
+    /// @brief Security operation has concluded and failed
+    BSL_SECOP_CONCLUSION_FAILURE
+} BSL_SecOper_ConclusionState_e;
+
 /** Block CRC types.
  * Defined in Section 4.2.1 of RFC 9171 @cite rfc9171.
  */

src/BSLConfig.h.in

@@ -67,6 +67,12 @@ const char * bsl_version(void);
 #define BSL_FREE free
 #endif /* BSL_FREE */
 
+#ifndef BSL_CALLOC
+/** Uses the same function signature as C99 calloc().
+ */
+#define BSL_CALLOC calloc
+#endif /* BSL_CALLOC */
+
 /** Define to override value/struct allocation.
  * See m-core.h for details.
  */

src/CMakeLists.txt

@@ -110,6 +110,7 @@ set_target_properties(bsl_sample_pp
         SOVERSION ${CMAKE_PROJECT_VERSION_MAJOR}
 )
 target_link_libraries(bsl_sample_pp PUBLIC bsl_front)
+target_link_libraries(bsl_sample_pp PUBLIC MLIB::mlib)
 
 # Dynamic backend library
 set(BSL_DYNAMIC_H
@@ -128,6 +129,7 @@ set(BSL_DYNAMIC_C
   ${CMAKE_CURRENT_SOURCE_DIR}/backend/SecOutcome.c
   ${CMAKE_CURRENT_SOURCE_DIR}/backend/SecParam.c
   ${CMAKE_CURRENT_SOURCE_DIR}/backend/SecResult.c
+  ${CMAKE_CURRENT_SOURCE_DIR}/backend/SecurityAction.c
   ${CMAKE_CURRENT_SOURCE_DIR}/backend/SecurityActionSet.c
   ${CMAKE_CURRENT_SOURCE_DIR}/backend/SecurityContext.c
   ${CMAKE_CURRENT_SOURCE_DIR}/backend/SecurityResultSet.c

src/backend/AbsSecBlock.c

@@ -120,7 +120,7 @@ bool BSL_AbsSecBlock_ContainsTarget(const BSL_AbsSecBlock_t *self, uint64_t targ
 {
     ASSERT_PRECONDITION(BSL_AbsSecBlock_IsConsistent(self));
     for
-        M_EACH(target_num, self->targets, LIST_OPLIST(uint64_list))
+        M_EACH(target_num, self->targets, M_ARRAY_OPLIST(uint64_list))
         {
             if (*target_num == target_block_num)
             {

src/backend/AbsSecBlock.h

@@ -48,6 +48,7 @@
 // NOLINTBEGIN
 /// @cond Doxygen_Suppress
 M_ARRAY_DEF(uint64_list, uint64_t)
+/// @endcond
 // NOLINTEND
 
 /** Represents the Abstract Security Block as defined in RFC9172