133 Add dynamic memory mgmt callbacks to host descriptors (#141)

* Remove #defines and add host descriptor callbacks for mem mgmt

* Add docs to bsl private mem mgmt fns

* Modify unit tests to set host desc first; add defualt libc

* Add docs to host desc struct for dynamic mem cbs

* Add test for dyn mem cbs

* MockBPA dyn mem patch

* diff fix

* apply format ubuntu

* Spelling fix

* 133 Move dyn mem bcbs to seperate struct

* Rename BSL dynamic mem fns to lowercase

* apply format ubuntu

* 133 refactor setter

* apply format ubuntu

* Moved libc defaults into a macro. Fixed API docs.

* format

* spelling

---------

Co-authored-by: Brian Sipos <brian.sipos@jhuapl.edu>

Author: jeronstone

docs/api/10-bsl-developers.md

@@ -209,17 +209,20 @@ After its de-initialization the members of the struct will no longer have well d
 
 To help with troubleshooting, de-initialization should set pointers set to NULL and other values to a well-defined state. One option is to use `memset()` to zeroize the entire struct.
 
-# Macros
+## Memory Management Functions
 
-This section contains references to commonly used macros defined for the BSL
+When heap memory is needed at BSL runtime, the following functions are used and have the same signature and semantics as the corresponding C99 functions indicated below.
 
-## Memory Management Macros
+- [BSL_malloc](@ref BSL_malloc) as `malloc()`
+- [BSL_realloc](@ref BSL_realloc) as `realloc()`
+- [BSL_calloc](@ref BSL_calloc) as `calloc()`
+- [BSL_free](@ref BSL_free) as `free()`
 
-When heap memory is needed at BSL runtime, the following macros are used and have the same signature and semantics as the corresponding C99 functions indicated below.
+These can be modified using the @ref BSL_DynMemHostDescriptors_t interface.
 
-- [BSL_MALLOC](@ref BSL_MALLOC) as `malloc()`
-- [BSL_REALLOC](@ref BSL_REALLOC) as `realloc()`
-- [BSL_FREE](@ref BSL_FREE) as `free()`
+# Macros
+
+This section contains references to commonly used macros defined for the BSL
 
 ## Error Checking Handler Macros
 

docs/api/dictionary.txt

@@ -123,6 +123,7 @@ JSON
 JWK
 KEK
 len
+libc
 LibCtx
 lifecycle
 Lifecycles

src/BPSecLib_Private.h

@@ -425,6 +425,27 @@ int BSL_HostEIDPattern_DecodeFromText(BSL_HostEIDPattern_t *pat, const char *tex
  */
 bool BSL_HostEIDPattern_IsMatch(const BSL_HostEIDPattern_t *pat, const BSL_HostEID_t *eid);
 
+/// @brief Dynamic memory allocation
+/// @param size size of allocation
+/// @return valid heap pointer
+void *BSL_malloc(size_t size);
+
+/// @brief Dynamic memory reallocation
+/// @param ptr existing dynamic memory pointer
+/// @param size new allocation size
+/// @return valid heap pointer
+void *BSL_realloc(void *ptr, size_t size);
+
+/// @brief Contiguous dynamic memory allocation
+/// @param nmemb number of members to allocate
+/// @param size size of each member
+/// @return valid heap pointer
+void *BSL_calloc(size_t nmemb, size_t size);
+
+/// @brief Free dynamically allocated memory
+/// @param ptr pointer to memory to free
+void BSL_free(void *ptr);
+
 /** Block types using IANA-assigned code points from @cite iana:bundle.
  */
 typedef enum

src/BPSecLib_Public.h

@@ -260,6 +260,42 @@ typedef struct BSL_CanonicalBlock_s
     size_t   btsd_len;  ///< Length in bytes of the BTSD accessible through sequential APIs
 } BSL_CanonicalBlock_t;
 
+/** Dynamic memory callback descriptors used by Dynamic BPA descriptor.
+ *
+ * These are meant to be used as part of ::BSL_HostDescriptors_t for
+ * registering host callbacks.
+ */
+typedef struct
+{
+    /** Dynamic memory allocation callback.
+     *
+     *  @return valid heap pointer on success, NULL on failure.
+     */
+    void *(*malloc_cb)(size_t size);
+
+    /** Dynamic memory re-allocation callback.
+     *
+     *  @return valid heap pointer on success, NULL on failure.
+     */
+    void *(*realloc_cb)(void *ptr, size_t size);
+
+    /** Contiguous dynamic memory allocation callback.
+     *
+     *  @return valid 0-initialized heap pointer on success, NULL on failure.
+     */
+    void *(*calloc_cb)(size_t nmemb, size_t size);
+
+    /** Free dynamic memory allocation callback.
+     */
+    void (*free_cb)(void *ptr);
+} BSL_DynMemHostDescriptors_t;
+
+/// Default heap functions from libc
+#define BSL_DynMemHostDescriptors_DEFAULT                                                 \
+    {                                                                                     \
+        .malloc_cb = malloc, .realloc_cb = realloc, .calloc_cb = calloc, .free_cb = free, \
+    }
+
 /** Dynamic BPA descriptor.
  */
 typedef struct
@@ -350,6 +386,10 @@ typedef struct
 
     /// @brief Host BPA function that returns true if the given EID matched an EID pattern.
     bool (*eidpat_match)(const BSL_HostEIDPattern_t *pat, const BSL_HostEID_t *eid, void *user_data);
+
+    /// @brief Optionally set dynamic memory management callbacks. Defaults to libc calls if unset.
+    BSL_DynMemHostDescriptors_t dyn_mem_desc;
+
 } BSL_HostDescriptors_t;
 
 /** Set the BPA descriptor (callbacks) for this process.

src/BSLConfig.h.in

@@ -53,30 +53,6 @@ extern "C" {
  */
 const char * bsl_version(void);
 
-#ifndef BSL_MALLOC
-/** Uses the same function signature as C99 malloc().
- */
-#define BSL_MALLOC malloc
-#endif /* BSL_MALLOC */
-
-#ifndef BSL_REALLOC
-/** Uses the same function signature as C99 realloc().
- */
-#define BSL_REALLOC realloc
-#endif /* BSL_REALLOC */
-
-#ifndef BSL_FREE
-/** Uses the same function signature as C99 free().
- */
-#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 */
-
 /** Force the use of M_ prefixed macros for M*LIB
  */
 //#define M_USE_SMALL_NAME 0
@@ -85,25 +61,25 @@ const char * bsl_version(void);
 /** Define to override value/struct allocation.
  * See m-core.h for details.
  */
-#define M_MEMORY_ALLOC(type) ((type *) BSL_MALLOC(sizeof(type)))
+#define M_MEMORY_ALLOC(type) ((type *) BSL_malloc(sizeof(type)))
 
 #undef M_MEMORY_DEL
 /** Define to override value/struct deallocation.
  * See m-core.h for details.
  */
-#define M_MEMORY_DEL(ptr) BSL_FREE(ptr)
+#define M_MEMORY_DEL(ptr) BSL_free(ptr)
 
 #undef M_MEMORY_REALLOC
 /** Define to override array allocation.
  * See m-core.h for details.
  */
-#define M_MEMORY_REALLOC(type, ptr, n) (M_UNLIKELY((n) > SIZE_MAX / sizeof(type)) ? (type *) NULL : (type *) BSL_REALLOC((ptr), (n)*sizeof (type)))
+#define M_MEMORY_REALLOC(type, ptr, n) (M_UNLIKELY((n) > SIZE_MAX / sizeof(type)) ? (type *) NULL : (type *) BSL_realloc((ptr), (n)*sizeof (type)))
 
 #undef M_MEMORY_FREE
 /** Define to override array deallocation.
  * See m-core.h for details.
  */
-#define M_MEMORY_FREE(ptr) BSL_FREE(ptr)
+#define M_MEMORY_FREE(ptr) BSL_free(ptr)
 
 #ifdef __cplusplus
 } // extern C

src/CryptoInterface.h

@@ -215,7 +215,7 @@ int BSL_AuthCtx_Deinit(BSL_AuthCtx_t *hmac_ctx);
 /**
  * Deinit and free generated key handle
  * @param[in] keyhandle key handle to clear.
- * Key handle assumed to be generated, not present in key registry, and allocated with ::BSL_MALLOC().
+ * Key handle assumed to be generated, not present in key registry, and allocated with ::BSL_malloc().
  * @returns 0 if successfully cleared key handle
  */
 int BSL_Crypto_ClearGeneratedKeyHandle(void *keyhandle);
@@ -226,7 +226,7 @@ int BSL_Crypto_ClearGeneratedKeyHandle(void *keyhandle);
  * @param[in] kek_handle key encryption key handle (encryption key)
  * @param[in] cek_handle content encryption key handle (encryption data)
  * @param[in,out] wrapped_key output wrapped key (ciphertext) bytes
- * @param[in,out] wrapped_key_handle output wrapped key (ciphertext) handle, allocated with ::BSL_MALLOC(). Set to NULL
+ * @param[in,out] wrapped_key_handle output wrapped key (ciphertext) handle, allocated with ::BSL_malloc(). Set to NULL
  * if handle not needed.
  */
 int BSL_Crypto_WrapKey(void *kek_handle, void *cek_handle, BSL_Data_t *wrapped_key, void **wrapped_key_handle);
@@ -236,7 +236,7 @@ int BSL_Crypto_WrapKey(void *kek_handle, void *cek_handle, BSL_Data_t *wrapped_k
  * CEK size expected to match size of KEK
  * @param[in] kek_handle key encryption key handle (decryption key)
  * @param[in] wrapped_key input wrapped key (ciphertext) bytes
- * @param[in,out] cek_handle output content encryption key (plaintext) handle, allocated with ::BSL_MALLOC()
+ * @param[in,out] cek_handle output content encryption key (plaintext) handle, allocated with ::BSL_malloc()
  */
 int BSL_Crypto_UnwrapKey(void *kek_handle, BSL_Data_t *wrapped_key, void **cek_handle);
 
@@ -326,7 +326,7 @@ int BSL_Cipher_Deinit(BSL_Cipher_t *cipher_ctx);
 /**
  * Generate a new cryptographic key
  * @param[in] key_length length of new key. Should be 16 or 32
- * @param[in, out] key_out pointer to pointer for new key handle, allocated with ::BSL_MALLOC()
+ * @param[in, out] key_out pointer to pointer for new key handle, allocated with ::BSL_malloc()
  */
 int BSL_Crypto_GenKey(size_t key_length, void **key_out);
 

src/Data.c

@@ -42,7 +42,7 @@ static void bsl_data_int_free(BSL_Data_t *data)
 
     if (data->owned && data->ptr)
     {
-        BSL_FREE(data->ptr);
+        BSL_free(data->ptr);
     }
 }
 
@@ -59,7 +59,7 @@ int BSL_Data_InitBuffer(BSL_Data_t *data, size_t bytelen)
     CHK_ARG_EXPR(bytelen > 0);
 
     bsl_data_int_reset(data);
-    data->ptr   = BSL_MALLOC(bytelen);
+    data->ptr   = BSL_malloc(bytelen);
     data->len   = bytelen;
     data->owned = true;
     memset(data->ptr, 0, bytelen);
@@ -145,7 +145,7 @@ int BSL_Data_Resize(BSL_Data_t *data, size_t len)
     {
         data->ptr = NULL;
     }
-    BSL_DataPtr_t got = BSL_REALLOC(data->ptr, len);
+    BSL_DataPtr_t got = BSL_realloc(data->ptr, len);
     if (UNLIKELY(!got))
     {
         bsl_data_int_reset(data);

src/backend/HostInterface.c

@@ -27,7 +27,8 @@
 #include "UtilDefs_SeqReadWrite.h"
 
 // NOLINTNEXTLINE
-static BSL_HostDescriptors_t HostDescriptorTable = { 0 };
+/// Initialized to library default
+static BSL_HostDescriptors_t HostDescriptorTable = { .dyn_mem_desc = BSL_DynMemHostDescriptors_DEFAULT };
 
 int BSL_HostDescriptors_Set(BSL_HostDescriptors_t desc)
 {
@@ -48,6 +49,19 @@ int BSL_HostDescriptors_Set(BSL_HostDescriptors_t desc)
     CHK_PRECONDITION(desc.eidpat_deinit);
     CHK_PRECONDITION(desc.eidpat_from_text);
     CHK_PRECONDITION(desc.eidpat_match);
+
+    // If all callbacks are unset/NULL, use default
+    if (NULL == desc.dyn_mem_desc.malloc_cb && NULL == desc.dyn_mem_desc.realloc_cb
+        && NULL == desc.dyn_mem_desc.calloc_cb && NULL == desc.dyn_mem_desc.free_cb)
+    {
+        desc.dyn_mem_desc = (BSL_DynMemHostDescriptors_t)BSL_DynMemHostDescriptors_DEFAULT;
+    }
+    // otherwiese, if any one are unset, return error
+    else if (NULL == desc.dyn_mem_desc.malloc_cb || NULL == desc.dyn_mem_desc.realloc_cb
+             || NULL == desc.dyn_mem_desc.calloc_cb || NULL == desc.dyn_mem_desc.free_cb)
+    {
+        return BSL_ERR_ARG_NULL;
+    }
     // GCOV_EXCL_STOP
 
     HostDescriptorTable = desc;
@@ -224,3 +238,23 @@ bool BSL_HostEIDPattern_IsMatch(const BSL_HostEIDPattern_t *pat, const BSL_HostE
     ASSERT_PRECONDITION(HostDescriptorTable.eidpat_match);
     return HostDescriptorTable.eidpat_match(pat, eid, HostDescriptorTable.user_data);
 }
+
+void *BSL_malloc(size_t size)
+{
+    return HostDescriptorTable.dyn_mem_desc.malloc_cb(size);
+}
+
+void *BSL_realloc(void *ptr, size_t size)
+{
+    return HostDescriptorTable.dyn_mem_desc.realloc_cb(ptr, size);
+}
+
+void *BSL_calloc(size_t nmemb, size_t size)
+{
+    return HostDescriptorTable.dyn_mem_desc.calloc_cb(nmemb, size);
+}
+
+void BSL_free(void *ptr)
+{
+    HostDescriptorTable.dyn_mem_desc.free_cb(ptr);
+}

src/backend/PublicInterfaceImpl.c

@@ -91,7 +91,7 @@ void BSL_PrimaryBlock_deinit(BSL_PrimaryBlock_t *obj)
 {
     ASSERT_ARG_NONNULL(obj);
 
-    BSL_FREE(obj->block_numbers);
+    BSL_free(obj->block_numbers);
     obj->block_numbers = NULL;
 
     BSL_Data_Deinit(&obj->encoded);
@@ -174,7 +174,7 @@ int BSL_API_QuerySecurity(const BSL_LibCtx_t *bsl, BSL_SecurityActionSet_t *outp
                 BSL_SeqReader_Get(btsd_read, btsd_copy.ptr, &btsd_copy.len);
                 BSL_SeqReader_Destroy(btsd_read);
 
-                BSL_AbsSecBlock_t *abs_sec_block = BSL_CALLOC(1, BSL_AbsSecBlock_Sizeof());
+                BSL_AbsSecBlock_t *abs_sec_block = BSL_calloc(1, BSL_AbsSecBlock_Sizeof());
                 BSL_AbsSecBlock_InitEmpty(abs_sec_block);
                 if (BSL_AbsSecBlock_DecodeFromCBOR(abs_sec_block, &btsd_copy) == 0)
                 {
@@ -189,7 +189,7 @@ int BSL_API_QuerySecurity(const BSL_LibCtx_t *bsl, BSL_SecurityActionSet_t *outp
                     BSL_SecOper_SetReasonCode(sec_oper, BSL_REASONCODE_BLOCK_UNINTELLIGIBLE);
                 }
                 BSL_AbsSecBlock_Deinit(abs_sec_block);
-                BSL_FREE(abs_sec_block);
+                BSL_free(abs_sec_block);
 
                 BSL_Data_Deinit(&btsd_copy);
             }

src/backend/SecurityContext.c

@@ -481,7 +481,7 @@ int BSL_SecCtx_ExecutePolicyActionSet(BSL_LibCtx_t *lib, BSL_SecurityResponseSet
      *  - BCB will be a special case, since it actively manipulates the BTSD
      *
      */
-    BSL_SecOutcome_t *outcome = BSL_CALLOC(1, BSL_SecOutcome_Sizeof());
+    BSL_SecOutcome_t *outcome = BSL_calloc(1, BSL_SecOutcome_Sizeof());
 
     BSL_SecActionList_it_t act_it;
     for (BSL_SecActionList_it(act_it, action_set->actions); !BSL_SecActionList_end_p(act_it);
@@ -535,7 +535,7 @@ int BSL_SecCtx_ExecutePolicyActionSet(BSL_LibCtx_t *lib, BSL_SecurityResponseSet
             BSL_SecurityResponseSet_AppendResult(output_response, errcode, sec_oper->policy_action);
         }
     }
-    BSL_FREE(outcome);
+    BSL_free(outcome);
 
     return BSL_SUCCESS;
 }