The latest updates to the Espressif-specific integration of wolfSSL bring a significant enhancement for developers working on memory-constrained embedded systems: support for using PSRAM (pseudo-static RAM) during wolfSSL heap operations.
This improvement not only unlocks larger memory capacity for cryptographic operations, but also lays the foundation for more stable and scalable TLS communication on ESP32 and other Espressif-based platforms.
Why more stable?
Some of the ESP32 chip types have relatively little RAM. Once a large and complex application is written, there may be little leftover room for TLS exchanges. Heap corruption and / or stack overflows will typically ensue, causing undesired stability problems.
What Changed?
The recent GitHub Pull Request #8987 introduces a set of enhancements that allow dynamic memory allocation routines in wolfSSL to take advantage of the extended PSRAM region (when available). This is especially valuable on platforms such as the ESP32-WROVER, ESP32-C3, and ESP32-S3 which support external PSRAM.
Here’s a breakdown of the key updates:
Custom Allocator Integration
wolfSSL can now check for application-defined memory allocators using wolfSSL_GetAllocators() before falling back to the default FreeRTOS pvPortMalloc() or realloc() calls. This opens up new flexibility.
For instance, add these #define statements to the wolfssl user_settings.h file.
#define XMALLOC_USER #define XFREE MY_FREE #define XMALLOC MY_MALLOC
Then implement custom FREE and MALLOC in the application.
void MY_FREE(void *p, void* heap, int type)
{
free(p);
}
void* MY_MALLOC(size_t sz, void* heap, int type)
{
return malloc(sz);
}
With this mechanism, if your app defines a heap allocator that maps to PSRAM (e.g., via heap_caps_malloc(…, MALLOC_CAP_SPIRAM)), wolfSSL will use it.
XREALLOC / XMALLOC / XFREE Wrappers Updated
Custom memory macros (XMALLOC, XFREE, XREALLOC) were updated to redirect to the new PSRAM-aware versions in esp_sdk_mem_lib.c. Debug versions were added as well:
#define XMALLOC(s, h, type) \
wc_pvPortMalloc((s)) // Uses PSRAM-aware allocator
Debug-Friendly Memory Tracing
For developers debugging memory usage, verbose allocation logging was added when either DEBUG_WOLFSSL or DEBUG_WOLFSSL_MALLOC are defined. This makes it easier to catch leaks, misallocations, or fragmentation in systems where memory is limited.
ESP_LOGE("malloc", "Failed Allocating memory of size: %d bytes", size);
Benefits of PSRAM Integration
Embedded systems often face memory limitations, especially when running TLS sessions, parsing certificates, or handling large buffers. By enabling PSRAM usage in wolfSSL:
- Larger TLS Buffers: Allows larger I/O buffers and longer certificate chains without heap exhaustion.
- Stronger Security: Enables features like TLS 1.3 with minimal compromise on memory availability.
- Scalability: Supports more simultaneous connections or sessions on memory-constrained MCUs.
- Debugging Support: Optional debug builds can now track allocations and reallocation failures with file/line/function info.
How to Enable It
This integration is automatic if you’re using wolfSSL on ESP-IDF and PSRAM is configured in your project.
For full benefit:
Ensure your build enables PSRAM via menuconfig:
Component config – ESP32-specific – Support for external – SPI-connected RAM
Optionally implement custom allocators using heap_caps_malloc() targeting PSRAM:
void* my_malloc(size_t sz) {
return heap_caps_malloc(sz, MALLOC_CAP_SPIRAM | MALLOC_CAP_8BIT);
}
Register your allocators:
wolfSSL_SetAllocators(my_malloc, my_free, my_realloc);
As a reminder: No more than CONFIG_LWIP_MAX_SOCKETS sockets should be opened.
Example:
#ifndef NO_WOLFSSL_MEMORY
static void *custom_malloc(size_t size) {
void* this_custom_malloc;
this_custom_malloc = heap_caps_malloc(size, MALLOC_CAP_SPIRAM | MALLOC_CAP_8BIT);
return this_custom_malloc;
}
static void* custom_realloc(void* ptr, size_t size) {
void* this_custom_realloc;
this_custom_realloc = heap_caps_realloc(ptr, size, MALLOC_CAP_SPIRAM | MALLOC_CAP_8BIT);
return this_custom_realloc;
}
static void custom_free(void *ptr) {
heap_caps_free(ptr);
}
#endif
Then in the main app, use wolfSSL_SetAllocators:
#if defined(NO_WOLFSSL_MEMORY)
ESP_LOGE(TAG, "Cannot use wolfSSL_SetAllocators with NO_WOLFSSL_MEMORY");
#else
wolfSSL_SetAllocators((wolfSSL_Malloc_cb)custom_malloc,
(wolfSSL_Free_cb)custom_free,
(wolfSSL_Realloc_cb)custom_realloc);
#endif
esp_err_t error = heap_caps_register_failed_alloc_callback(heap_caps_alloc_failed_hook);
if (error == ESP_OK) {
ESP_LOGE(TAG, "Success: heap_caps_register_failed_alloc_callback");
}
else {
ESP_LOGE(TAG, "FAILED: heap_caps_register_failed_alloc_callback");
}
Tested Platforms
This change is specifically tailored for the Espressif ESP-IDF platform, including:
- ESP32-WROVER
- ESP32-S3
- ESP32-C3 (with PSRAM)
- Any module with external SPI RAM
Acknowledgements
We extend our thanks to Fidel for suggesting, contributing sample code, and helping to test this feature. Congratulations on getting 50 concurrent FreeRTOS tasks running on the ESP32, each communicating with wolfSSL Post Quantum algorithms!
Ing. Fidel Alejandro Rodríguez Corbo, Phd
Smart Electronics Research Group
School of Engineering and Science
Tecnologico de Monterrey,
Av. Eugenio Garza Sada 2501 Sur
Col. Tecnológico, C.P. 64849
Monterrey, Nuevo León, México
Final Thoughts
This patch brings wolfSSL one step closer to optimal memory use in constrained environments. By supporting PSRAM, developers can offload cryptographic operations away from limited internal RAM – enhancing both stability and performance.
wolfSSL continues to push forward in embedded TLS innovation, and these improvements make it an even better fit for secure IoT applications on ESP32.
For more information or to contribute, visit wolfSSL GitHub and explore the Espressif-specific README.
If you have questions about any of the above, please contact us at facts@wolfssl.com or call us at +1 425 245 8247.
Download wolfSSL Now
