[crypto] PSA API: introduce platform API for crypto dynamic memory mgmt (#12290)

This commit introduces two new platform functions:
- otPlatCryptoCAlloc()
- otPlatCryptoFree()

It also provides a default implementation using the OpenThread Heap.

This API is necessary for the upcoming work related to PSA API

Signed-off-by: Łukasz Duda <lukasz.duda@nordicsemi.no>

include/openthread/instance.h

@@ -52,7 +52,7 @@ extern "C" {
  *
  * @note This number versions both OpenThread platform and user APIs.
  */
-#define OPENTHREAD_API_VERSION (571)
+#define OPENTHREAD_API_VERSION (572)
 
 /**
  * @addtogroup api-instance

include/openthread/platform/crypto.h

@@ -291,6 +291,31 @@ otError otPlatCryptoDestroyKey(otCryptoKeyRef aKeyRef);
  */
 bool otPlatCryptoHasKey(otCryptoKeyRef aKeyRef);
 
+/**
+ * Dynamically allocates new memory for the Crypto subsystem. On platforms that support it, they should redirect to
+ * `calloc`. For those that don't support `calloc`, they should implement the standard `calloc` behavior.
+ *
+ * See: https://man7.org/linux/man-pages/man3/calloc.3.html
+ *
+ * Is required for `OPENTHREAD_CONFIG_HEAP_EXTERNAL_ENABLE`.
+ *
+ * @param[in] aNum   The number of blocks to allocate
+ * @param[in] aSize  The size of each block to allocate
+ *
+ * @retval void*  The pointer to the front of the memory allocated
+ * @retval NULL   Failed to allocate the memory requested.
+ */
+void *otPlatCryptoCAlloc(size_t aNum, size_t aSize);
+
+/**
+ * Frees memory that was dynamically allocated by `otPlatCryptoCAlloc()`.
+ *
+ * Is required for `OPENTHREAD_CONFIG_HEAP_EXTERNAL_ENABLE`.
+ *
+ * @param[in] aPtr  A pointer the memory blocks to free. The pointer may be NULL.
+ */
+void otPlatCryptoFree(void *aPtr);
+
 /**
  * Initialize the HMAC operation.
  *

include/openthread/platform/memory.h

@@ -51,18 +51,17 @@ extern "C" {
  */
 
 /*
- * OpenThread only requires dynamic memory allocation when supporting multiple simultaneous instances, for MbedTls.
+ * Dynamic memory allocation is primarily needed for Thread Border Router functionalities and protocols
+ * such as SRP (server), mDNS or DHCPv6 PD. It may also be used for OpenThread message buffers.
  */
 
 /**
- * Dynamically allocates new memory. On platforms that support it, should just redirect to calloc. For
- * those that don't support calloc, should support the same functionality:
+ * Dynamically allocates new memory. On platforms that support it, they should redirect to `calloc`. For
+ * those that don't support `calloc`, they should implement the standard `calloc` behavior.
  *
- *   "The calloc() function contiguously allocates enough space for count objects that are size bytes of
- *   memory each and returns a pointer to the allocated memory. The allocated memory is filled with bytes
- *   of value zero."
+ * See: https://man7.org/linux/man-pages/man3/calloc.3.html
  *
- * Is required for OPENTHREAD_CONFIG_HEAP_EXTERNAL_ENABLE.
+ * Is required for `OPENTHREAD_CONFIG_HEAP_EXTERNAL_ENABLE`.
  *
  * @param[in] aNum   The number of blocks to allocate
  * @param[in] aSize  The size of each block to allocate
@@ -73,9 +72,9 @@ extern "C" {
 void *otPlatCAlloc(size_t aNum, size_t aSize);
 
 /**
- * Frees memory that was dynamically allocated.
+ * Frees memory that was dynamically allocated by `otPlatCAlloc()`.
  *
- * Is required for OPENTHREAD_CONFIG_HEAP_EXTERNAL_ENABLE.
+ * Is required for `OPENTHREAD_CONFIG_HEAP_EXTERNAL_ENABLE`.
  *
  * @param[in] aPtr  A pointer the memory blocks to free. The pointer may be NULL.
  */

src/core/crypto/crypto_platform.cpp

@@ -47,6 +47,7 @@
 #include <openthread/instance.h>
 #include <openthread/platform/crypto.h>
 #include <openthread/platform/entropy.h>
+#include <openthread/platform/memory.h>
 #include <openthread/platform/time.h>
 
 #include "common/code_utils.hpp"
@@ -78,6 +79,11 @@ static constexpr uint16_t kEntropyMinThreshold = 16;
 #endif
 #endif
 
+#if OPENTHREAD_CONFIG_HEAP_EXTERNAL_ENABLE
+OT_TOOL_WEAK void *otPlatCryptoCAlloc(size_t aNum, size_t aSize) { return otPlatCAlloc(aNum, aSize); }
+OT_TOOL_WEAK void  otPlatCryptoFree(void *aPtr) { otPlatFree(aPtr); }
+#endif
+
 OT_TOOL_WEAK void otPlatCryptoInit(void)
 {
     // Intentionally empty.

src/core/crypto/mbedtls.cpp

@@ -57,9 +57,9 @@ MbedTls::MbedTls(void)
     // mbedTLS's debug level is almost the same as OpenThread's
     mbedtls_debug_set_threshold(OPENTHREAD_CONFIG_LOG_LEVEL);
 #endif
-#if OPENTHREAD_CONFIG_ENABLE_BUILTIN_MBEDTLS_MANAGEMENT
+#if OPENTHREAD_CONFIG_ENABLE_BUILTIN_MBEDTLS_MANAGEMENT && !OPENTHREAD_CONFIG_HEAP_EXTERNAL_ENABLE
     mbedtls_platform_set_calloc_free(Heap::CAlloc, Heap::Free);
-#endif // OPENTHREAD_CONFIG_ENABLE_BUILTIN_MBEDTLS_MANAGEMENT
+#endif
 }
 
 Error MbedTls::MapError(int aMbedTlsError)

tests/unit/test_platform.cpp

@@ -106,6 +106,10 @@ extern "C" {
 OT_TOOL_WEAK void *otPlatCAlloc(size_t aNum, size_t aSize) { return calloc(aNum, aSize); }
 
 OT_TOOL_WEAK void otPlatFree(void *aPtr) { free(aPtr); }
+
+OT_TOOL_WEAK void *otPlatCryptoCAlloc(size_t aNum, size_t aSize) { return calloc(aNum, aSize); }
+
+OT_TOOL_WEAK void otPlatCryptoFree(void *aPtr) { free(aPtr); }
 #endif
 
 OT_TOOL_WEAK void otTaskletsSignalPending(otInstance *) {}

third_party/mbedtls/mbedtls-config.h

@@ -134,8 +134,8 @@
 #define MBEDTLS_ENTROPY_MAX_SOURCES        1 /**< Maximum number of sources supported */
 
 #if OPENTHREAD_CONFIG_HEAP_EXTERNAL_ENABLE
-#define MBEDTLS_PLATFORM_STD_CALLOC      otPlatCAlloc /**< Default allocator to use, can be undefined */
-#define MBEDTLS_PLATFORM_STD_FREE        otPlatFree /**< Default free to use, can be undefined */
+#define MBEDTLS_PLATFORM_STD_CALLOC      otPlatCryptoCAlloc /**< Default allocator to use, can be undefined */
+#define MBEDTLS_PLATFORM_STD_FREE        otPlatCryptoFree   /**< Default free to use, can be undefined */
 #else
 #define MBEDTLS_MEMORY_BUFFER_ALLOC_C
 #endif