Release 3.2.0

.clang-format

@@ -1,18 +1,47 @@
-# Tested with Ubuntu clang-format version 14.0.0-1ubuntu1.1
-
-BreakBeforeBinaryOperators: All
-
-ColumnLimit: 120
-
+# Language conformance: C11
+# Using Cpp as a language is ok here, since there is no separate C formatter.
+# It is common to use Cpp for C code formatting in clang-format.
+Language: Cpp
+Standard: Cpp11
 BasedOnStyle: Google
 
+# --- BRACE STYLE ---
+# "Functions... opening brace on new line" 
+# "if, for, while... opening brace on the same line" 
 BreakBeforeBraces: Stroustrup
 
+# --- INDENTATION & WIDTH ---
+ColumnLimit: 103
+
+# "You shall indent the code with 4 spaces" 
 IndentWidth: 4
+TabWidth: 4
+UseTab: Never
+ContinuationIndentWidth: 4
 
+# --- POINTERS ---
+# Google defaults to Left, but guidelines show Right (void *p) 
 PointerAlignment: Right
+DerivePointerAlignment: false
+
+# --- SPECIFIC TROPIC SQUARE RULES ---
+# "You shall place braces around the single statement" 
+# Valid since Clang-Format 15
+InsertBraces: true
+
+# "You shall put spaces after... if, switch..." 
+SpaceBeforeParens: ControlStatements
+# "You shall not add spaces around (inside) parenthesized expressions" 
+SpacesInParentheses: false
+
+# "Space on each side of most binary and ternary operators" 
+# Note: "SpacesInBinaryOperators" is implicit in Google style, no key needed.
+SpaceBeforeAssignmentOperators: true
 
-# # Insert New line at EOF if missing
-#InsertNewlineAtEOF: true
-# # Set EOL to LF unconditionally
-#LineEnding: LF
+# Misc Cleanup
+SortIncludes: true
+IndentCaseLabels: true
+# Keep operators at the end of the line
+BreakBeforeBinaryOperators: None
+# Make breaking at '=' very expensive so it forces breaks inside arguments instead
+PenaltyBreakAssignment: 100

.github/workflows/clang_format_check.yml

@@ -6,11 +6,15 @@ on:
       - develop
     paths:
       - '**.c'
+      - '**.cpp'
       - '**.h'
+      - '**.hpp'
   pull_request:
     paths:
       - '**.c'
+      - '**.cpp'
       - '**.h'
+      - '**.hpp'
 
 jobs:
   check-format:
@@ -21,7 +25,9 @@ jobs:
       uses: actions/checkout@v4
 
     - name: Install clang-format
-      run: sudo apt install -y clang-format
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y clang-format
 
     - name: Get files and check format
       run: |
@@ -31,7 +37,7 @@ jobs:
             echo "Formatting issue in $f"
             exit_code=1
           fi
-        done < <(find . -type f \( -name '*.c' -o -name '*.h' \) ! -path './vendor/*' ! -path './vendor/**' ! -path '*Vendor/*' ! -path '*_deps/*' ! -path './.git/*' -print0)
+        done < <(find . -type f \( -name '*.c' -o -name '*.cpp' -o -name '*.h' -o -name '*.hpp' \) ! -path './vendor/*' ! -path './vendor/**' ! -path '*Vendor/*' ! -path '*_deps/*' ! -path './.git/*' -print0)
 
         if [ $exit_code -ne 0 ]; then
           echo "Clang-format check failed."

.github/workflows/coverage.yml

@@ -42,6 +42,7 @@ jobs:
 
       - name: Install dependencies
         run: |
+            sudo apt-get update
             sudo apt-get install cmake build-essential ninja-build
             ./tests/functional/model/download_deps.sh
             ./scripts/tropic01_model/install_linux.sh

.github/workflows/functional_mock_tests.yml

@@ -26,6 +26,7 @@ jobs:
 
       - name: Install dependencies
         run: |
+            sudo apt-get update
             sudo apt-get install cmake build-essential ninja-build
             pip install jsonschema jinja2
 
@@ -58,6 +59,7 @@ jobs:
 
       - name: Install dependencies
         run: |
+            sudo apt-get update
             sudo apt-get install cmake build-essential valgrind ninja-build
             pip install jsonschema jinja2
 

.github/workflows/integration_tests.yml

@@ -26,6 +26,7 @@ jobs:
 
       - name: Install dependencies
         run: |
+            sudo apt-get update
             sudo apt-get install cmake build-essential ninja-build
             ./tests/functional/model/download_deps.sh
             ./scripts/tropic01_model/install_linux.sh
@@ -69,6 +70,7 @@ jobs:
 
       - name: Install dependencies
         run: |
+            sudo apt-get update
             sudo apt-get install cmake build-essential valgrind ninja-build
             ./tests/functional/model/download_deps.sh
             ./scripts/tropic01_model/install_linux.sh

.github/workflows/linux_build_examples.yml

@@ -24,6 +24,7 @@ jobs:
 
       - name: Install dependencies
         run: |
+            sudo apt-get update
             sudo apt-get install cmake build-essential ninja-build
             pip3 install jsonschema
 
@@ -41,6 +42,10 @@ jobs:
           cmake ./ -B build -G Ninja
           cd build && ninja
 
+          cd ../../full_chain_verification
+          cmake ./ -B build -G Ninja
+          cd build && ninja
+
       - name: Build USB Devkit examples
         run: |
           cd examples/linux/usb_devkit/hello_world

.github/workflows/model_run_examples.yml

@@ -24,6 +24,7 @@ jobs:
 
       - name: Install dependencies
         run: |
+            sudo apt-get update
             sudo apt-get install cmake build-essential valgrind ninja-build
             ./tests/functional/model/download_deps.sh
             ./scripts/tropic01_model/install_linux.sh

.github/workflows/release_new_version.yml

@@ -72,6 +72,7 @@ jobs:
 
       - name: Install dependencies
         run: |
+            sudo apt-get update
             sudo apt-get install doxygen graphviz
             pip install -r docs/requirements.txt
 

.github/workflows/static_analysis.yml

@@ -17,6 +17,7 @@ jobs:
     steps:
       - name: Install dependencies
         run: |
+            sudo apt-get update
             sudo apt-get install cmake build-essential cppcheck
 
       - name: Checkout Repository

.github/workflows/stm32_build_examples.yml

@@ -24,6 +24,7 @@ jobs:
 
       - name: Install dependencies
         run: |
+            sudo apt-get update
             sudo apt-get install cmake build-essential ninja-build gcc-arm-none-eabi
             pip3 install jsonschema
 

CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.2.0]
+
+### Changed
+- Renamed `lt_secure_memzero.h` to `libtropic_secure_memzero.h` and moved it to `include/`, so it is available in HAL.
+
+### Added
+- Examples: Added full certificate chain verification example for Linux SPI.
+- HAL: HAL for STM32U5xx series
+- Documentation: new tutorial for the TROPIC01 model - **Understanding Libtropic**.
+
+### Fixed
+- Size of `l3_chunk` member of `lt_l2_encrypted_cmd_req_t` and `lt_l2_encrypted_cmd_rsp_t` structs to `TR01_L2_CHUNK_MAX_DATA_SIZE`.
+- `hal/`: don't include `libtropic_port.h` in HAL headers if not used.
+- `lt_init()` is successful even if TROPIC01 has invalid Application FW, so Libtropic can be used in Start-up Mode.
+- STM32: securely wipe secrets when generating random numbers.
+- STM32: change type of `baudrate_prescaler` (inside `lt_dev_stm32_nucleo_f439zi_t` and `lt_dev_stm32_nucleo_l432kc_t`) to `uint32_t`.
+
+### Removed
+
 ## [3.1.0]
 
 ### Changed

CMakeLists.txt

@@ -113,7 +113,7 @@ get_directory_property(HAS_PARENT_SCOPE PARENT_DIRECTORY)
 ###########################################################################
 
 project(libtropic_SDK
-        VERSION 3.1.0
+        VERSION 3.2.0
         DESCRIPTION "TROPIC01 software development kit"
         HOMEPAGE_URL "https://tropicsquare.github.io/libtropic/latest/"
         LANGUAGES C)
@@ -134,7 +134,7 @@ set(SDK_SRCS ${SDK_SRCS}
     ${CMAKE_CURRENT_SOURCE_DIR}/src/lt_asn1_der.c
     ${CMAKE_CURRENT_SOURCE_DIR}/src/libtropic_default_sh0_keys.c
     ${CMAKE_CURRENT_SOURCE_DIR}/src/lt_tr01_attrs.c
-    ${CMAKE_CURRENT_SOURCE_DIR}/src/lt_secure_memzero.c
+    ${CMAKE_CURRENT_SOURCE_DIR}/src/libtropic_secure_memzero.c
 )
 
 set(SDK_INCS ${SDK_INCS}
@@ -143,6 +143,7 @@ set(SDK_INCS ${SDK_INCS}
     ${CMAKE_CURRENT_SOURCE_DIR}/include/libtropic_port.h
     ${CMAKE_CURRENT_SOURCE_DIR}/include/libtropic_l2.h
     ${CMAKE_CURRENT_SOURCE_DIR}/include/libtropic_l3.h
+    ${CMAKE_CURRENT_SOURCE_DIR}/include/libtropic_secure_memzero.h
     ${CMAKE_CURRENT_SOURCE_DIR}/src/lt_crc16.h
     ${CMAKE_CURRENT_SOURCE_DIR}/src/lt_port_wrap.h
     ${CMAKE_CURRENT_SOURCE_DIR}/src/lt_l1.h

CONTRIBUTING.md

@@ -5,7 +5,7 @@ We love contributions! To make contributing simple for both sides, please:
 - Create a branch from the develop branch and do the changes:
     - Make sure to follow specifics in our [Coding Style](#coding-style).
     - Make sure to use [Code Formatter](#code-formatter), otherwise the PR check will fail and cannot be merged.
-    - Make sure the branch passes [Tests](https://tropicsquare.github.io/libtropic/latest/for_contributors/functional_tests/) against model -- otherwise, the PR check will fail.
+    - Make sure the branch passes [functional tests](https://tropicsquare.github.io/libtropic/latest/for_contributors/tests/functional_tests/) against TROPIC01 Model and [functional mock tests](https://tropicsquare.github.io/libtropic/latest/for_contributors/tests/functional_mock_tests/), otherwise, the PR check will fail.
     - Make sure to run [Static Analysis](#static-analysis).
     - Make sure your [Commit Messages](#commit-messages) follow our guidelines.
 - Create pull request.

README.md

@@ -2,59 +2,46 @@
 
 ![](https://github.com/tropicsquare/libtropic/actions/workflows/integration_tests.yml/badge.svg) ![](https://github.com/tropicsquare/libtropic/actions/workflows/build_docs_master.yml/badge.svg)
 
-TROPIC01's SDK written in C. Contributors, please follow [guidelines](https://github.com/tropicsquare/libtropic/blob/master/CONTRIBUTING.md).
+**Libtropic** is the official C SDK for TROPIC01, **the open and auditable secure element by [Tropic Square](https://tropicsquare.com/)**.
 
-For more information about TROPIC01 chip and its **datasheet** or **User API**, check out developers resources in the [TROPIC01](https://github.com/tropicsquare/tropic01) repository.
+The repository provides the library and integration examples for practical evaluation of the chip. For information about particular TROPIC01 part number or for general insights into TROPIC01 design, please follow the link to [TROPIC01](https://github.com/tropicsquare/tropic01) product page.
 
-## Documentation
-We recommend using the [Libtropic documentation](https://tropicsquare.github.io/libtropic/latest/) as the source of truth for getting information about Libtropic.
+## Getting started
 
-The documentation is generated only for the releases and the version can be switched via the version selector at the top of the page.
+Want to learn **TROPIC01** the easy way? See our [Tutorials](https://tropicsquare.github.io/libtropic/latest/tutorials/) and start today!
 
-## Compatibility with TROPIC01 firmware versions
+## Firmware compatibility
 
-For the Libtropic library to function correctly with the TROPIC01 secure element, the versions of four key components must be compatible:
+For correct operation, these four versions must be compatible:
 
-1. **Libtropic SDK**: The version of this library.
-2. **Bootloader FW**: Bootloader firmware running on the TROPIC01's RISC-V CPU after power-up. It cannot be updated.
-2. **Application FW**: Application firmware running on the TROPIC01's RISC-V CPU. It can be updated.
-3. **SPECT FW**: Firmware running on the TROPIC01's SPECT co-processor. It can be updated.
+1. **Libtropic SDK**: Version of this library.
+2. **Bootloader FW**: Firmware running on TROPIC01 RISC-V CPU after power-up (cannot be updated).
+3. **Application FW**: Firmware running on TROPIC01 RISC-V CPU (can be updated).
+4. **SPECT FW**: Firmware running on the TROPIC01 SPECT co-processor (can be updated).
 
-For more information about each of these, refer to the [TROPIC01](https://github.com/tropicsquare/tropic01) repository.
+For details, see particular part number in [TROPIC01](https://github.com/tropicsquare/tropic01).
 
-The following table outlines the tested and supported compatibility between released versions:
-
-| Libtropic | Application FW | SPECT FW | Bootloader FW |  Tests             |
+| Libtropic | Application FW | SPECT FW | Bootloader FW | Tests              |
 |:---------:|:--------------:|:--------:|:-------------:|:------------------:|
 | 1.0.0     | 1.0.0          | 1.0.0    | 1.0.1-2.0.1   | :white_check_mark: |
 | 2.0.0     | 1.0.0–1.0.1    | 1.0.0    | 2.0.1         | :white_check_mark: |
 | 2.0.1     | 1.0.0–1.0.1    | 1.0.0    | 2.0.1         | :white_check_mark: |
 | 3.0.0     | 1.0.0–2.0.0    | 1.0.0    | 2.0.1         | :white_check_mark: |
 | 3.1.0     | 1.0.0–2.0.0    | 1.0.0    | 2.0.1         | :white_check_mark: |
+| 3.2.0     | 1.0.0–2.0.0    | 1.0.0    | 2.0.1         | :white_check_mark: |
 
 > [!WARNING]
-> Using mismatched versions of the components may result in unpredictable behavior or errors. It is strongly advised to use the latest compatible versions of all components to ensure proper functionality. 
-
-For retrieving firmware versions from TROPIC01 and updating its firmware, refer to the [Tutorials](https://tropicsquare.github.io/libtropic/latest/tutorials/) and select your platform. Follow the instructions for **Chip Identification** and **Firmware Update** example.
-
-## Repository structure
-* `CMakeLists.txt` Root CMake project file
-* `cmake/` CMake related files
-* `cal/` Implementation of Crypto Abstraction Layers (CAL) for supported Cryptographic Functionality Providers (CFP)
-* `docs/` [MkDocs](https://www.mkdocs.org/) Documentation deployed [here](https://tropicsquare.github.io/libtropic/latest/)
-* `examples/` Example projects for each supported platform
-* `hal/` Implementation of Hardware Abstraction Layers (HAL) for supported host platforms
-* `include/` Public API header files
-* `scripts/` Build and config scripts
-* `src/` Library's source files
-* `tests/` Functional tests
-* `TROPIC01_fw_update_files/` Files used for updating TROPIC01's firmware
-* `vendor/` Third party libraries and tools
+> Mismatched component versions may cause errors or unpredictable behavior. Use the latest compatible versions whenever possible.
+
+To read firmware versions and update firmware, use the [Tutorials](https://tropicsquare.github.io/libtropic/latest/tutorials/) and follow **Chip Identification** and **Firmware Update**.
 
 ## FAQ
-We provide the [FAQ](https://tropicsquare.github.io/libtropic/latest/faq/) section in our documentation with frequently asked questions and troubleshooting tips.
+
+See the [FAQ](https://tropicsquare.github.io/libtropic/latest/faq/) for common questions and troubleshooting.
 
 ## License
 
-See the [LICENSE.md](LICENSE.md) file in the root of this repository or consult license information at [Tropic Square website](http:/tropicsquare.com/license).
+See [LICENSE.md](LICENSE.md) in the repository root, or check the [Tropic Square website](https://tropicsquare.com/license).
+
+