STMicroelectronics · dgarske · Jan 6, 2026
diff --git a/doc/resources/Markdown/04_PORTING_GUIDE/03_PORTINNG_GUIDE.md b/doc/resources/Markdown/04_PORTING_GUIDE/03_PORTINNG_GUIDE.md
@@ -41,3 +41,19 @@ Following platform files architecture are recommended to simplify the porting of
 - @subpage stse_platform_power
 - @subpage stse_platform_i2c
 - @subpage stse_platform_st1wire
+
+# Reference Implementations
+
+The following reference implementations are available for common cryptographic libraries:
+
+## STM32 CMOX Library
+
+The examples above demonstrate implementation using the STM32 Cryptographic Library (CMOX), which is optimized for STM32 microcontrollers.
+
+## wolfSSL/wolfCrypt Library
+
+A complete reference implementation using wolfSSL/wolfCrypt is available for platforms where wolfSSL is the cryptographic provider. This implementation supports Linux, RTOS, and bare-metal environments.
+
+- @subpage stse_platform_wolfssl
+
+See also the `examples/wolfssl/` directory for ready-to-use implementation files.
diff --git a/doc/resources/Markdown/04_PORTING_GUIDE/PAL_files/stse_platform_wolfssl.c.md b/doc/resources/Markdown/04_PORTING_GUIDE/PAL_files/stse_platform_wolfssl.c.md
@@ -0,0 +1,164 @@
+# wolfSSL/wolfCrypt Platform Implementation {#stse_platform_wolfssl}
+
+The `stse_platform_crypto_wolfssl.c` file provides a complete cryptographic platform implementation for the STSecureElement library using wolfSSL/wolfCrypt as the cryptographic provider. This implementation serves as an alternative to the STM32 CMOX library for platforms using wolfSSL.
+
+## Overview
+
+[wolfSSL](https://www.wolfssl.com/) is a lightweight, portable, C-language-based SSL/TLS library with an embedded cryptographic library (wolfCrypt). This platform implementation enables STSELib integration on any system where wolfSSL is available, including:
+
+- Linux/POSIX systems
+- Embedded systems (ARM Cortex-M, RISC-V, etc.)
+- RTOS environments (FreeRTOS, Zephyr, etc.)
+- Custom microcontroller platforms
+
+## Features Supported
+
+| Category | Functions | wolfSSL API Used |
+|----------|-----------|------------------|
+| **Hash** | `stse_platform_hash_compute` | `wc_Sha256Hash`, `wc_Sha384Hash` |
+| **AES-ECB** | `stse_platform_aes_ecb_enc` | `wc_AesEncryptDirect` |
+| **AES-CBC** | `stse_platform_aes_cbc_enc`, `stse_platform_aes_cbc_dec` | `wc_AesCbcEncrypt`, `wc_AesCbcDecrypt` |
+| **AES-CMAC** | `stse_platform_aes_cmac_*` | Manual RFC 4493 implementation using `wc_AesCbcEncrypt` |
+| **HMAC/HKDF** | `stse_platform_hmac_sha256_*` | `wc_HmacSetKey`, `wc_HmacUpdate`, `wc_HmacFinal` |
+| **ECC Verify** | `stse_platform_ecc_verify` | `wc_ecc_verify_hash` |
+| **ECC KeyGen** | `stse_platform_ecc_generate_key_pair` | `wc_ecc_make_key_ex`, `wc_curve25519_make_key`, `wc_ed25519_make_key` |
+| **ECC Sign** | `stse_platform_ecc_sign` | `wc_ecc_sign_hash`, `wc_ed25519_sign_msg` |
+| **ECDH** | `stse_platform_ecc_ecdh` | `wc_ecc_shared_secret`, `wc_curve25519_shared_secret` |
+| **Key Wrap** | `stse_platform_nist_kw_encrypt` | `wc_AesKeyWrap` |
+
+## ECC Curve Support
+
+| STSE Key Type | wolfSSL Curve ID | Notes |
+|---------------|------------------|-------|
+| `STSE_ECC_KT_NIST_P_256` | `ECC_SECP256R1` | Default curve |
+| `STSE_ECC_KT_NIST_P_384` | `ECC_SECP384R1` | |
+| `STSE_ECC_KT_NIST_P_521` | `ECC_SECP521R1` | Requires `HAVE_ECC521` |
+| `STSE_ECC_KT_BP_P_256` | `ECC_BRAINPOOLP256R1` | Requires `HAVE_ECC_BRAINPOOL` |
+| `STSE_ECC_KT_BP_P_384` | `ECC_BRAINPOOLP384R1` | Requires `HAVE_ECC_BRAINPOOL` |
+| `STSE_ECC_KT_BP_P_512` | `ECC_BRAINPOOLP512R1` | Requires `HAVE_ECC_BRAINPOOL` |
+| `STSE_ECC_KT_CURVE25519` | `ECC_X25519` | Requires `HAVE_CURVE25519` |
+| `STSE_ECC_KT_ED25519` | `ECC_ED25519` | Requires `HAVE_ED25519` |
+
+## Configuration
+
+### wolfSSL Build Requirements
+
+The wolfSSL library must be built with the following features enabled:
+
+```bash
+./configure --enable-ecc --enable-sha384 --enable-sha512 \
+            --enable-aescbc --enable-cmac --enable-keywrap \
+            --enable-curve25519 --enable-ed25519 \
+            --enable-brainpool
+```
+
+Or define in `user_settings.h`:
+
+```c
+#define WOLFSSL_USER_SETTINGS
+
+/* ECC Support */
+#define HAVE_ECC
+#define TFM_ECC256
+#define ECC_TIMING_RESISTANT
+
+/* Hash Support */
+#define WOLFSSL_SHA384
+#define WOLFSSL_SHA512
+
+/* AES Support */
+#define HAVE_AES_CBC
+#define WOLFSSL_AES_DIRECT
+#define HAVE_AES_KEYWRAP
+
+/* HMAC/HKDF Support */
+#define HAVE_HKDF
+
+/* Optional: Additional curves */
+#define HAVE_ECC_BRAINPOOL
+#define HAVE_CURVE25519
+#define HAVE_ED25519
+```
+
+### STSE Configuration
+
+In your `stse_conf.h`, enable the required features:
+
+```c
+/* Hash algorithms */
+#define STSE_CONF_HASH_SHA_256
+#define STSE_CONF_HASH_SHA_384
+
+/* ECC curves */
+#define STSE_CONF_ECC_NIST_P_256
+#define STSE_CONF_ECC_NIST_P_384
+
+/* Session/Key establishment features */
+#define STSE_CONF_USE_HOST_KEY_ESTABLISHMENT
+#define STSE_CONF_USE_HOST_SESSION
+```
+
+## Implementation Details
+
+### AES-CMAC Implementation
+
+The AES-CMAC implementation follows RFC 4493 using wolfSSL's AES-CBC primitive. Subkeys K1 and K2 are generated according to the specification, and the streaming init/append/finish API is supported for processing data in chunks.
+
+### Signature Format Conversion
+
+STSE uses raw R||S signature format, while wolfSSL uses DER encoding. The implementation handles conversion using:
+- `wc_ecc_rs_raw_to_sig()` - Convert R||S to DER for verification
+- `wc_ecc_sig_to_rs()` - Convert DER to R||S after signing
+
+### Public Key Format
+
+Public keys are expected in raw X||Y coordinate format (uncompressed, without the 0x04 prefix). The implementation uses `wc_ecc_import_unsigned()` and `wc_ecc_export_public_raw()` for conversion.
+
+## Usage Example
+
+```c
+#include "stselib.h"
+#include "stse_conf.h"
+
+/* Include wolfSSL with user settings */
+#define WOLFSSL_USER_SETTINGS
+#include "user_settings.h"
+#include <wolfssl/wolfcrypt/settings.h>
+
+int main(void)
+{
+    stse_Handler_t stse_handler;
+    stse_ReturnCode_t ret;
+
+    /* Initialize STSE (calls stse_platform_crypto_init internally) */
+    ret = stse_init(&stse_handler, STSAFE_A120, 1, 0x20);
+    if (ret != STSE_OK) {
+        return -1;
+    }
+
+    /* Now use STSE APIs - platform crypto is ready */
+    /* ... */
+
+    return 0;
+}
+```
+
+## File Location
+
+The reference implementation is located at:
+- `examples/wolfssl/stse_platform_crypto_wolfssl.c`
+
+Copy this file to your platform directory and include it in your build.
+
+## License
+
+The wolfSSL platform implementation is provided under the wolfSSL license. wolfSSL is dual-licensed under GPLv2 and a commercial license. For commercial use, please contact wolfSSL Inc.
+
+## References
+
+- [wolfSSL Documentation](https://www.wolfssl.com/documentation/)
+- [wolfSSL GitHub](https://github.com/wolfSSL/wolfssl)
+- [RFC 4493 - AES-CMAC](https://tools.ietf.org/html/rfc4493)
+- [RFC 5869 - HKDF](https://tools.ietf.org/html/rfc5869)
+- [NIST SP 800-38F - Key Wrap](https://csrc.nist.gov/publications/detail/sp/800-38f/final)
+
diff --git a/examples/wolfssl/README.md b/examples/wolfssl/README.md
@@ -0,0 +1,79 @@
+# wolfSSL Platform Implementation for STSELib
+
+This directory contains a reference implementation of the STSELib Platform Abstraction Layer (PAL) using wolfSSL/wolfCrypt as the cryptographic provider.
+
+## Files
+
+| File | Description |
+|------|-------------|
+| `stse_platform_crypto_wolfssl.c` | Complete crypto PAL implementation |
+| `user_settings.h` | Sample wolfSSL configuration |
+
+## Quick Start
+
+1. **Copy files to your project:**
+   ```bash
+   cp stse_platform_crypto_wolfssl.c /your/project/platform/
+   cp user_settings.h /your/project/
+   ```
+
+2. **Configure your build to include:**
+   - wolfSSL library (with `WOLFSSL_USER_SETTINGS` defined)
+   - STSELib headers
+   - Your platform-specific I2C/delay implementations
+
+3. **Build and link with wolfSSL:**
+   ```bash
+   gcc -DWOLFSSL_USER_SETTINGS -I. -I/path/to/wolfssl -I/path/to/STSELib \
+       your_app.c stse_platform_crypto_wolfssl.c \
+       -lwolfssl -o your_app
+   ```
+
+## Features Implemented
+
+- ✅ SHA-256/SHA-384 hashing
+- ✅ AES-ECB/CBC encryption/decryption
+- ✅ AES-CMAC (streaming and one-shot)
+- ✅ HMAC-SHA256 HKDF (extract/expand)
+- ✅ ECC signature verification (NIST P-256/P-384, Brainpool, Ed25519)
+- ✅ ECC key pair generation
+- ✅ ECDSA/EdDSA signing
+- ✅ ECDH key exchange (including Curve25519)
+- ✅ NIST AES Key Wrap
+
+## Requirements
+
+### wolfSSL Configuration
+
+Minimum required features in `user_settings.h` or configure:
+
+```c
+#define HAVE_ECC
+#define HAVE_AES_CBC
+#define WOLFSSL_AES_DIRECT
+#define WOLFSSL_SHA384
+#define WOLFSSL_SHA512
+```
+
+### Optional Features
+
+For full curve support:
+```c
+#define HAVE_ECC_BRAINPOOL
+#define HAVE_CURVE25519
+#define HAVE_ED25519
+#define HAVE_AES_KEYWRAP
+```
+
+## Testing
+
+This implementation has been tested with:
+- STSAFE-A120 on Raspberry Pi 5
+- wolfSSL 5.x
+- Linux I2C driver
+
+## License
+
+Copyright 2025 wolfSSL Inc. Licensed under GPLv2 or commercial license.
+See https://www.wolfssl.com/license/ for details.
+