Improve PlatformIO Certificate Bundle Support

[gojimmypi]

Draft - testing still in progress, not all examples updated with wolfSSL component files.

Description

This PR improves the build experience with wolfSSL when using PlatformIO for:

• Improved Certificate Bundle flexibility.
• Better visibility to key CMake messages, including at wolfSSL_Init() time.
• Update all core wolfSSL Espressif examples with new user_settings.h, Kconfig, CMakeLists.txt files.

Note that the concept of a Certificate Bundles is non-standard, with no RCF, and has been implemented at wolfSSL only for Espressif SDK compatibility and consistency. This is to allow customers to easily migrate to wolfSSL. See wolfSSL Manual: Keys and Certificates for the recommended usage.

Getting Started with wolfSSL on PlatformIO

See blog: https://www.wolfssl.com/wolfssl-now-supported-on-platformio/

Background

PlatformIO works slightly differently with ESP-IDF CMake as compared to using the idf.py build.

One key difference is regarding the silent failure to call scripts at build time, for example the gen_crt_bundle.py for either the Espressif SDK mbedtls component or for the wolfSSL component.

Reminder: the resulting file from gen_crt_bundle.py when called for the mbedTLS component file is NOT binary compatible with the file generated by the wolfssl component.

Additionally, all environments using CMake have an issue where once built the first time, many CMake files remain cached and some messages are not regenerated, not visible on subsequent builds.

See also

• Add wolfSSL esp-tls and Certificate Bundle Support #7936
• Viewing output from CMake platformio/platformio-vscode-ide#4318
• Python scripts not executed in Espressif build? platformio/platformio-vscode-ide#4296 (comment)
• https://gitlab.kitware.com/cmake/cmake/-/issues/20463
• The howsmyssl site does not fully support TLS 1.3 (IDFGH-13611) espressif/esp-idf#14496

Core wolfSSL

Introduction of HAVE_LIBWOLFSSL_OUTPUT_HEADER. This macro is defined when multiple calls are make to the new CMake function APPEND_LIBWOLFSSL_CMAKE_OUTPUT("message").

Normally, prior versions of the LIBWOLFSSL_SAVE_INFO saved simple values to compile definitions, for example git attributes.

In this update there's an optional build-time-generated libwolfssl_output.h that contains properly formatted multi-line messages. Sample contents:

/* libwolfssl_output.h generated by wolfssl component */
#ifndef _LIBWOLFSSL_OUTPUT_H_

#define _LIBWOLFSSL_OUTPUT_H_

#define LIBWOLFSSL_CMAKE_OUTPUT \
"\n" \
"wolfSSL Certificate Bundles Enabled\n" \
"Special processing for wolfSSL Certificate Bundles\n" \
"Not using a custom wolfSSL bundle path\n" \


#endif

When HAVE_LIBWOLFSSL_OUTPUT_HEADER is defined, the esp32_util.c will now #include "libwolfssl_output.h".

The Espressif ShowExtendedSystemInfo has been modified to also show the contents of LIBWOLFSSL_CMAKE_OUTPUT.

This addition to wolfSSL_Init(void) at initialization time prints the CMake messages when available:

    WOLFSSL_ENTER("wolfSSL_Init");

#if defined(LIBWOLFSSL_CMAKE_OUTPUT)
    WOLFSSL_MSG(LIBWOLFSSL_CMAKE_OUTPUT);
#else
    WOLFSSL_MSG("No extra wolfSSL cmake messages found");
#endif

Certificate Bundles

The respective wolfssl component CMakeLists.txt has been modified to use an explicit bundle file, instead of generating at build time.

There are new options in the wolfSSL Kconfig used by the idp.py menuconfig to enable alternate certificate bundle locations. This is particularly helpful for PlatformIO that does not generate a bundle. Others may also appreciate the flexibility to have a fixed bundle, possibly custom, and optionally outside of the normal build and source directories.

See new options:

• CONFIG_WOLFSSL_ALTERNATE_CERTIFICATE_BUNDLE to enable alternate location
• WOLFSSL_ALTERNATE_CERTIFICATE_BUNDLE_PATH_AND_NAME to provide relative or fully qualified file name and path

A new macro is introduced explicitly to provide more informative debug messages: SHOW_WOLFSSL_BUNDLE_ERROR(err). This is available only when CONFIG_WOLFSSL_DEBUG_CERT_BUNDLE is enabled.

There's a new option NO_WOLFSSL_USE_ASM_CERT to use a custom _binary_x509_crt_bundle_wolfssl_start instead of the default asm file:

    extern const uint8_t x509_crt_imported_bundle_wolfssl_bin_start[]
                         asm("_binary_x509_crt_bundle_wolfssl_start");

Some environments outside of the ESP-IDF may need to have the Python cryptography installed, so the pio_install_cryptography.py is also included here.

Other Changes

Introduction of CONFIG_ESP_WOLFSSL_NO_STACK_SIZE_BUILD_WARNING. This allows disabling of the RSA minimum memory warning at compile time. This is useful when wolfSSL is running in a task other than main.

Minor cleanup, spelling corrections.

Fixes zd# 20015

Testing

How did you test?

Manual testing with customer, automated testing with my Espressif jig.

Tested with:

• PlatformIO Core 6.1.18·Home 3.4.4
• VSCode Version: 1.100.2 (user setup)
  Commit: 848b80aeb52026648a8ff9f7c45a9b0a80641e2e
  Date: 2025-05-14T21:47:40.416Z
  Electron: 34.5.1
  ElectronBuildId: 11369351
  Chromium: 132.0.6834.210
  Node.js: 20.19.0
  V8: 13.2.152.41-electron.0
  OS: Windows_NT x64 10.0.26100

Also tested with:

• Visual Studio 2022
  Version 17.12.5
  VisualStudio.17.Release/17.12.5+35728.132
  VisualGDB 6.0R8 (build 5338)

See also my fork of ESP-IDF with improved eps-tls support for wolfssl

For platformio.ini this is:

[env]
platform = [email protected]  # https://github.com/platformio/platform-espressif32/releases/tag/v6.8.0 uses ESP-IDF v5.3
# ESP-IDF v5.3.1 (20240926c)
platform_packages = framework-espidf @ https://github.com/gojimmypi/esp-idf/releases/download/v5.3.1.20240926c/esp-idf-v5.3.1.20240926c.zip

For PlatformIO from command-line Windows/DOS:

cd [project]

set PATH=%PATH%;C:\Users\%USERNAME%\.platformio\penv\Scripts\
pio run -t clean
rm -rf .pio
pio run -v > mybuild.log
pio device list
pio run --target upload
pio device monitor

Checklist

• added tests
• updated/added doxygen
• updated appropriate READMEs
• Updated manual and documentation

[gojimmypi]

Jenkins retest this please

For failure to connect to node

[JacobBarthelmeh]

Looks like this picked up a merge conflict. Please rebase/resolve and reassign to @wolfSSL-Bot when ready.

[gojimmypi]

Jenkins retest this please

For Unable to create live FilePath for wolf-linux-cloud-node-[n]; wolf-linux-cloud-node-[n] was marked offline: Connection was broken