1# wolfSSL STM32 Example for STM32 Cube IDE 2 3This example includes: 4 5* wolfCrypt test 6* wolfCrypt benchmark 7* wolfSSL TLS client/server test using in-memory transfers 8 9These examples use the Cube HAL for STM32. 10 11## Requirements 12 13You need both the STM32 IDE and the STM32 initialization code generator (STM32CubeMX) tools. The STM32CubeMX tool is used to setup a project which is used by the IDE to make any required code level changes and program / debug the STM32. 14 15* STM32CubeIDE: Integrated Development Environment for STM32 [https://www.st.com/en/development-tools/stm32cubeide.html](https://www.st.com/en/development-tools/stm32cubeide.html) 16* STM32CubeMX: STM32Cube initialization code generator [https://www.st.com/en/development-tools/stm32cubemx.html](https://www.st.com/en/development-tools/stm32cubemx.html) 17 18## STM32 Cube Pack 19 20### STM32 Cube Pack Installation 21 221. Download [wolfSSL Cube Pack](https://www.wolfssl.com/files/ide/I-CUBE-wolfSSL.pack) 232. Run the “STM32CubeMX” tool. 243. Under “Manage software installations” pane on the right, click “INSTALL/REMOVE” button. This can be also found by clicking "Help" -> "Managed embedded software packages" 254. From Local and choose “I-CUBE-wolfSSL.pack”. 265. Accept the GPLv2 license. Contact wolfSSL at sales@wolfssl.com for a commercial license and support/maintenance. 27 28### STM32 Cube Pack Usage 29 301. Create or open a Cube Project based on your hardware. See the sections below for creating a project and finding the example projects. 312. Under “Software Packs” choose “Select Components”. 323. Find and check all components for the wolfSSL.wolfSSL packs (wolfSSL / Core, wolfCrypt / Core and wolfCrypt / Test). Close 334. Under the “Software Packs” section click on “wolfSSL.wolfSSL” and configure the parameters. 345. For Cortex-M recommend “Math Configuration” -> “Single Precision Cortex-M Math” for the fastest option. 356. Hit the "Generate Code" button 367. Open the project in STM32CubeIDE 378. The Benchmark example uses float. To enable go to "Project Properties" -> "C/C++ Build" -> "Settings" -> "Tool Settings" -> "MCU Settings" -> Check "Use float with printf". 389. To enable printf make the `main.c` changes below in the [STM32 Printf](#stm32-printf) section. 39 40### STM32 Cube Pack Examples 41 42In the `I-CUBE-wolfSSL.pack` pack there are pre-assembled example projects available. 43After installing the pack you can find these example projects in `STM32Cube/Repository/Packs/wolfSSL/wolfSSL/[Version]/Projects`. 44To use an example: 45 461. Open STM32CubeIDE 472. Choose "Import" -> "Import an Existing STM32CubeMX Configuration File (.ioc)". 483. Browse to find the .ioc in `STM32Cube/Repository/Packs/wolfSSL/wolfSSL/[Version]/Projects` and click finish. 49 50### Creating your own STM32CubeMX configuration 51 52If none of the examples fit your STM32 type then you can create your own in STM32CubeMX by doing the following: 53 541. Create a project with the correct STM32 model. 552. Click on the "Software Packs" drop down near the top and choose "Select Components". 563. Expand the "wolfSSL" pack twice and check all the components. Then exit this menu. 574. Under "System Core" select "SYS" and changed the "Timebase Source" to TIM1. 585. Under "Timers" select "RTC" and make sure this is enabled. 596. Under "Connectivity" enable whichever UART/USART you have a serial I/O connected to. 607. Under "Middleware" select "FREERTOS" and change the interface to "CMSIS_V2". 61 1. Increase the "TOTAL_HEAP_SIZE", preferably to 120000 but on smaller chips such as the F107 you may only be able to increase this to 40000. 62 2. Enable "USE_MALLOC_FAILED_HOOK". 63 3. Change "CHECK_FOR_STACK_OVERFLOW" to "Option2". 64 4. Under "Tasks and Queues" select Add for a new task. 65 5. Set the "Task Name" to "wolfCrypt". 66 6. Set the "Stack Size" to 8960 or as high as you can close to that. The "Heap Usage" will show an error if this is too high. 67 7. Set the "Entry Function" to "wolfCryptDemo". 68 8. Set the "Code Generation Option" to "As external". 698. In "Software Packs" select "wolfSSL" and change any options as required. 709. Go to "Clock Configuration" and set the "HCLK" as high as the tool will let you. 7110. In "Project Manager" select the "STM32CubeIDE" toolchain. 72 73When you get to the IDE make sure you edit `wolfSSL.I-CUBE-wolfSSL_conf.h` to set the `HAL_CONSOLE_UART` to the correct one for your configuration. 74 75## Configuration 76 77The settings for the wolfSSL CubeMX pack are in the generated `wolfSSL.I-CUBE-wolfSSL_conf.h` file. An example of a generated file can be found at `examples/configs/user_settings_stm32.h`. 78 79The template used for generation is `IDE/STM32Cube/default_conf.ftl`, which is stored in the pack here: `STM32Cube/Repository/Packs/wolfSSL/wolfSSL/[Version]/CubeMX/templates/default_conf.ftl`. 80 81If the default settings for the Cube GUI are insufficient you can customize the build using one of these methods to prevent the changes from being overwritten when generating the code: 82 83* Copy the `wolfSSL.I-CUBE-wolfSSL_conf.h` to `Core/Inc` and rename to `user_settings.h`. Then add the preprocessor macro `WOLFSSL_USER_SETTINGS` to your project. This will use the `user_settings.h` instead of the generated configuration. 84 85OR 86 87* Edit the source template file used for Cube pack generation here: `STM32Cube/Repository/Packs/wolfSSL/wolfSSL/[Version]/CubeMX/templates/default_conf.ftl`. 88 89 90The section for "Hardware platform" may need to be adjusted depending on your processor and board: 91 92* To enable STM32F1 support define `WOLFSSL_STM32F1`. 93* To enable STM32F2 support define `WOLFSSL_STM32F2`. 94* To enable STM32F4 support define `WOLFSSL_STM32F4`. 95* To enable STM32F7 support define `WOLFSSL_STM32F7`. 96* To enable STM32L4 support define `WOLFSSL_STM32L4`. 97* To enable STM32L5 support define `WOLFSSL_STM32L5`. 98* To enable STM32H7 support define `WOLFSSL_STM32H7`. 99* To enable STM32WB support define `WOLFSSL_STM32WB`. 100 101To use the STM32 Cube HAL support make sure `WOLFSSL_STM32_CUBEMX` is defined. 102 103The L5 and WB55 support ECC PKA acceleration, which is enabled with `WOLFSSL_STM32_PKA`. 104 105To disable hardware crypto acceleration you can define: 106 107* `NO_STM32_HASH` 108* `NO_STM32_CRYPTO` 109 110To enable the latest Cube HAL support please define `STM32_HAL_V2`. 111 112If you'd like to use the older Standard Peripheral library undefine `WOLFSSL_STM32_CUBEMX`. 113 114With STM32 Cube HAL v2 some AES GCM hardware has a limitation for the AAD header, which must be a multiple of 4 bytes. 115 116If using `STM32_AESGCM_PARTIAL` with the following patch it will enable use for all AAD header sizes. The `STM32Cube_FW_F7_V1.16.0` patch is: 117 118```diff 119diff --git a/Drivers/STM32F7xx_HAL_Driver/Inc/stm32f7xx_hal_cryp.h b/Drivers/STM32F7xx_HAL_Driver/Inc/stm32f7xx_hal_cryp.h 120--- a/Drivers/STM32F7xx_HAL_Driver/Inc/stm32f7xx_hal_cryp.h 121+++ b/Drivers/STM32F7xx_HAL_Driver/Inc/stm32f7xx_hal_cryp.h 122@@ -63,6 +63,7 @@ typedef struct 123 GCM : also known as Additional Authentication Data 124 CCM : named B1 composed of the associated data length and Associated Data. */ 125 uint32_t HeaderSize; /*!< The size of header buffer in word */ 126+ uint32_t HeaderPadSize; /*!< <PATCH> The size of padding in bytes added to actual header data to pad it to a multiple of 32 bits </PATCH> */ 127 uint32_t *B0; /*!< B0 is first authentication block used only in AES CCM mode */ 128 uint32_t DataWidthUnit; /*!< Data With Unit, this parameter can be value of @ref CRYP_Data_Width_Unit*/ 129 uint32_t KeyIVConfigSkip; /*!< CRYP peripheral Key and IV configuration skip, to config Key and Initialization 130 131diff --git a/Drivers/STM32F7xx_HAL_Driver/Src/stm32f7xx_hal_cryp_ex.c b/Drivers/STM32F7xx_HAL_Driver/Src/stm32f7xx_hal_cryp_ex.c 132--- a/Drivers/STM32F7xx_HAL_Driver/Src/stm32f7xx_hal_cryp_ex.c 133+++ b/Drivers/STM32F7xx_HAL_Driver/Src/stm32f7xx_hal_cryp_ex.c 134@@ -132,6 +132,8 @@ HAL_StatusTypeDef HAL_CRYPEx_AESGCM_GenerateAuthTAG(CRYP_HandleTypeDef *hcryp, u 135 uint64_t inputlength = (uint64_t)hcryp->SizesSum * 8U; /* input length in bits */ 136 uint32_t tagaddr = (uint32_t)AuthTag; 137 138+ headerlength -= ((uint64_t)(hcryp->Init.HeaderPadSize) * 8U); /* <PATCH> Decrement the header size removing the pad size </PATCH> */ 139+ 140 if (hcryp->State == HAL_CRYP_STATE_READY) 141 { 142 /* Process locked */ 143``` 144 145If you are using FreeRTOS make sure your `FreeRTOSConfig.h` has its `configTOTAL_HEAP_SIZE` increased. 146 147The TLS client/server benchmark example requires about 76 KB for allocated tasks (with stack) and peak heap. This uses both a TLS client and server to test a TLS connection locally for each enabled TLS cipher suite. 148 149## Example `IDE/STM32Cube/wolfssl_example.c` Output 150 151``` 152....MENU 153 154.t. WolfCrypt Test 155.b. WolfCrypt Benchmark 156.l. WolfSSL TLS Bench 157.e. Show Cipher List 158 159Please select one of the above options: 160``` 161 162## Benchmarks 163 164See [STM32_Benchmarks.md](STM32_Benchmarks.md). 165 166Note: The Benchmark example uses float. To enable go to "Project Properties" -> "C/C++ Build" -> "Settings" -> "Tool Settings" -> "MCU Settings" -> Check "Use float with printf". 167 168## STM32 Printf 169 170In main.c make the following changes: 171 172This section needs to go below the `UART_HandleTypeDef` line, otherwise `wolfssl/wolfcrypt/settings.h` will error. 173 174```c 175/* Retargets the C library printf function to the USART. */ 176#include <stdio.h> 177#include <wolfssl/wolfcrypt/settings.h> 178#ifdef __GNUC__ 179int __io_putchar(int ch) 180#else 181int fputc(int ch, FILE *f) 182#endif 183{ 184 HAL_UART_Transmit(&HAL_CONSOLE_UART, (uint8_t *)&ch, 1, 0xFFFF); 185 186 return ch; 187} 188#ifdef __GNUC__ 189int _write(int file,char *ptr, int len) 190{ 191 int DataIdx; 192 for (DataIdx= 0; DataIdx< len; DataIdx++) { 193 __io_putchar(*ptr++); 194 } 195 return len; 196} 197#endif 198``` 199 200In the `main()` function make the follow `setvbuf()` additions after `HAL_Init()`. 201 202```c 203int main(void) 204{ 205 /* Reset of all peripherals, Initializes the Flash interface and the Systick. */ 206 HAL_Init(); 207 208 /* Turn off buffers, so I/O occurs immediately */ 209 setvbuf(stdin, NULL, _IONBF, 0); 210 setvbuf(stdout, NULL, _IONBF, 0); 211 setvbuf(stderr, NULL, _IONBF, 0); 212 213``` 214 215## Support 216 217For questions please email [support@wolfssl.com](mailto:support@wolfssl.com) 218