Category: wolfSSL/ wolfCrypt

We wanted to highlight a useful migration guide posted by Amazon for their AWS IoT Core with FreeRTOS showing how to migrate from mbedTLS to wolfSSL. The migration guide shows useful API mappings and how to expose PKCS11 capabilities.

Check out the FreeRTOS with mbedTLS to FreeRTOS with wolfSSL Migration Guide v1.0.

FreeRTOS is a real-time operating system used in many embedded systems. It is lightweight and optimized for microcontrollers and small processors. For systems using cryptography or TLS, wolfSSL is a perfect match, so we wanted to highlight a guide for migrating from mbedTLS to wolfSSL.

The AWS IoT Core is a managed cloud service for secure, reliable communication between embedded devices and the AWS Cloud. The AWS Iot Core requires TLS communication to establish connections.

Why Migrate from mbedTLS to wolfSSL?

Moving to wolfSSL offers several advantages for embedded environments, including:

• Smaller footprint and performance optimizations: wolfSSL provides a reduced memory footprint and faster cryptographic processing.
• Latest Protocols: It also includes full support for TLS 1.3 and DTLS 1.3, enabling shorter handshakes and stronger encryption.
• Professional support: Direct support from engineers who authored and maintained the code. Free pre-sales support and paid support plans available.
• Commercial licensing: While open source, wolfSSL also offers commercial licenses for proprietary projects
• FIPS 140-3 certified cryptographic software module, making it suitable for regulated industries.
• Easy integration and extensive resources: The library includes detailed documentation and examples, simplifying testing and adoption.
• Expanded algorithm support: wolfSSL includes cryptographic algorithms beyond mbedTLS’s offerings such as Post Quantum (PQ) ML-DSA, ML-KEM, XMSS and LMSS.
• Assembly optimizations for ARM Cortex-M and A. We typically see a 10x speedup using our hand crafted assembly speedups, which are available for all our commonly used symmetric and asymmetric algorithms.

Note: This migration guide is fairly dated. Since then wolfSSL has developed and maintains full PKCS11 support to either consume a PKCS11 provider or to be one through our wolfPKCS11 provider. We also support using a TPM 2.0 module as the cryptographic and storage provider for wolfPKCS11.

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

Have you heard the newest and most pervasive buzzword in online security? Recently, the most popular and over-hyped expression doing the rounds these days is “Cryptoagility”. Why do we think it is so overhyped? Because if you are simply looking for a definition, you’ll be hard pressed to find one. People who talk about it can barely define it.

Most will have you believe in a vague notion of being able to swap out algorithms in real time via the click of a mouse button. No need for reboots, updates or interference from system administrators. Some will even go as far as having the ability to swap different implementations of the same algorithms. Uber flexibility in the runtime environment.

Here at wolfSSL we have a more nuanced approach to cryptoagility. What we just described above is what we call RuntimebCryptoagility and if your system can accommodate it and you are willing to spend the resources to have it, then perhaps you might want to look into our wolfEngine and wolfProvider products.

The other kind of Cryptoagility where the wolfSSL team specializes in is Buildtime Cryptoagility. We recognize that when it comes to embedded systems, resources are at a premium and can not be wasted. With that in mind, currently unused algorithms and data are taking up valuable memory and footprint. For example, if you’re planning a post-quantum transition, having those algorithms in your firmware now might not be practical. With wolfBoot, our super efficient boot loader implementation, that migration is a simple and seamless firmware update away. When the time comes, rebuild your firmware with the algorithms required and have a seamless Cryptoagility experience.

Note that it has been this way for years. Here at wolfSSL, we didn’t need to create a new buzzword to serve our customers.

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

Selecting the right hardware for an embedded project can be a complex decision—but choosing a security library doesn’t have to be. wolfSSL offers broad platform support, running seamlessly on everything from bare-metal systems to full-featured operating systems. In this post, we’ll compare how wolfSSL integrates with two widely used embedded platforms: Xilinx and STM. While both are popular choices, they offer distinct differences in architecture, development tools, and integration workflows.

---

Platform High Level Overview

Xilinx

• Primarily FPGA-based (Zynq, Zynq Ultrascale+, Versal)
• Offers ARM Cortex-A cores alongside programmable logic
• Development environment: Xilinx Vitis / Petalinux
• OS: Often uses Linux (Yocto or Petalinux), FreeRTOS or bare-metal

STM (STMicroelectronics)

• Microcontroller-focused (e.g., STM32 family)
• Most are based on ARM Cortex-M cores, with some series using Cortex-A cores
• Development environment: STM32CubeIDE, Makefiles, or bare-metal toolchains
• OS: Often bare-metal or FreeRTOS

---

wolfSSL Build Process

Xilinx

• Autotools or CMake to build wolfSSL in userspace
• Cross-compilation with Petalinux SDK or Vitis toolchain
• Hardware acceleration via Xilinx’s crypto engine, ARM assembly optimizations or custom logic in the PL with crypto callbacks

STM (STMicroelectronics)

• Predefined example configuration files in wolfSSL/IDE/STM32Cube
• Integration with STM32CubeMX-generated projects
• Support for HAL/LL drivers, and FreeRTOS (if applicable)

---

Cryptographic Acceleration

Xilinx

• Advanced FPGAs allow for hardware acceleration of cryptographic primitives
• Can use custom IP cores or external crypto accelerators
• wolfSSL’s ARM assembly optimizations
• Potential for extreme performance gains, but at the cost of complexity

STM (STMicroelectronics)

• Some STM32 parts support hardware ECC, AES, SHA, and RNG
• wolfSSL can use these via direct calls to HAL drivers
• Easier to configure and use but offers less flexibility compared to FPGAs and on average has a less powerful CPU
• wolfSSL’s ARM assembly optimizations

---

Some Use Cases We See

• Xilinx if:
  • You need programmable logic and customizable crypto acceleration
  • Your application runs Linux and demands high throughput
  • You have a complex security architecture
• STM if:
  • You want quick integration for a bare-metal or FreeRTOS-based project
  • Your focus is low power and minimal footprint
  • You need an edge microcontroller

---

Both Xilinx and STM platforms are well-supported by wolfSSL, but the experience differs significantly. Xilinx generally offers power and flexibility—ideal for high-performance secure systems—while STM excels in simplicity and efficiency, making it perfect for lightweight, resource-constrained designs.

Whether you’re targeting a Linux-based Zynq application or a real-time STM32 sensor node, wolfSSL provides the building blocks you need to implement robust embedded security.

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

As of wolfSSL version 5.8.0, support for Curve25519 blinding has been introduced. Although originally listed as a feature addition in the changelog, it is more accurately characterized as a mitigation for a potential side-channel vulnerability affecting specific builds. This feature offers optional hardening against power or electromagnetic (EM) analysis during Curve25519 private key operations. While such attacks are generally difficult to execute in practice, enabling blinding provides an additional layer of protection for devices that may be more susceptible to physical access or side-channel observation.

When Blinding Is Applicable

Blinding is only relevant for builds that use the C implementation of Curve25519 in wolfSSL. It is not available or necessary in the following cases:

• Assembly-optimized implementations (–enable-armasm / WOLFSSL_ARMASM, –enable-intelasm / USE_INTEL_SPEEDUP)
• The small footprint Curve25519 build (–enable-curve25519=small / CURVE25519_SMALL)

To enable blinding in the C implementation, define the macro WOLFSSL_CURVE25519_BLINDING. For example:

bash
CopyEdit
./configure --enable-curve25519 CPPFLAGS=-DWOLFSSL_CURVE25519_BLINDING

Affected APIs

Blinding hardens operations where the private key is used with scalar multiplication, such as:

• wc_curve25519_export_public_ex – when deriving the public key from a private key
• wc_curve25519_make_key – during key pair generation
• wc_curve25519_generic
• wc_curve25519_shared_secret_ex

If you are using the C implementation on hardware where physical side-channel exposure is a concern, it’s recommended to enable blinding and regenerate private keys used in these operations. Curve25519 blinding will be enabled by default for the C implementation in future wolfSSL releases.

Acknowledgments

Thanks to Arnaud Varillon, Laurent Sauvage, and Allan Delautre from Telecom Paris for reporting this.

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

Introduction

The wolfSSL embedded SSL/TLS library has recently expanded its compatibility by adding support for the Open Watcom C/C++ compiler. This enhancement enables developers to build wolfSSL using Open Watcom across multiple platforms including Windows, Linux, and OS/2. This blog post explores the new Open Watcom support, its features, and how to leverage it in your projects.

What is Open Watcom?

Open Watcom is an open-source compiler suite derived from the commercial Watcom C/C++ compiler. It’s particularly valued for its:

• Cross-platform capabilities (Windows, OS/2, DOS, Linux)
• Efficient code generation
• Strong support for legacy systems
• Continued development by the open-source community

The compiler is especially important for maintaining and developing software for OS/2 and other legacy systems that still have active user communities.

New Features in wolfSSL for Open Watcom

The recent pull requests #8505 and #8484 have implemented several features to ensure wolfSSL works seamlessly with Open Watcom:

1. Multi-Platform Support:
   • Windows builds
   • Linux builds
   • OS/2 builds (particularly significant as OS/2 support is rare in modern libraries)
2. Build Configuration Options:
   • Single-threaded and multi-threaded builds
   • Static library and DLL (Dynamic Link Library) options
   • Compatibility with Open Watcom 1.9 and newer versions (2.0+)
3. OS/2-Specific Enhancements:
   • Socket handling for OS/2 networking
   • Thread management for OS/2’s unique threading model
   • Proper mutex implementation for OS/2
4. Technical Improvements:
   • Renamed OFFSETOF macro to WC_OFFSETOF to avoid conflicts with OS/2 headers
   • Added proper time handling functions for Open Watcom
   • Implemented conditional compilation for platform-specific code
   • Fixed socket and I/O handling for cross-platform compatibility

Use Cases and Benefits

The addition of Open Watcom support opens up several possibilities:

1. Legacy System Integration: Integrate modern TLS security into legacy systems running OS/2 or older Windows versions.
2. Cross-Platform Development: Develop secure applications that can be compiled for multiple platforms using a single compiler.
3. Educational Environments: Universities and educational institutions that use Open Watcom for teaching can now incorporate wolfSSL in their security curriculum.
4. Embedded Systems: Some embedded systems with specific requirements may benefit from Open Watcom’s efficient code generation.

Summary

The addition of Open Watcom support to wolfSSL shows our versatility by supporting this compiler across Windows, Linux, and especially OS/2 platforms. This feature enables developers working with legacy systems, educational environments, and specific embedded platforms to leverage wolfSSL’s robust security features.

The implementation includes comprehensive support for different threading models and library types, ensuring that developers have flexibility in how they integrate wolfSSL into their projects. Whether you’re maintaining legacy applications, teaching security concepts, or developing cross-platform solutions, the Open Watcom support in wolfSSL provides a valuable tool in your development arsenal.

As the security landscape continues to evolve, this enhancement ensures that even systems using older or specialized compilers can maintain modern security standards through wolfSSL’s TLS implementation.

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

We’re thrilled to announce a new feature in wolfSSL 5.8.0: the ability to offload Extended Master Secret (EMS) generation to hardware, introduced in Pull Request #8303. Integrated into `–enable-pkcallbacks –enable-extended-master` builds, this enhancement empowers developers to leverage Trusted Execution Environments (TEEs) or custom hardware for EMS generation, boosting security and performance in TLS sessions. This makes wolfSSL an even more robust solution for embedded systems, IoT, and high-security applications.

What is Extended Master Secret Offloading?

The Extended Master Secret (EMS), defined in RFC 7627, strengthens TLS session security by tying the master secret to the full handshake transcript, mitigating man-in-the-middle attacks. The new feature in wolfSSL allows developers to offload EMS generation to hardware, such as a Trusted Execution Environment (e.g., ARM TrustZone, Intel SGX) or specialized cryptographic hardware. By using a custom callback function, you can delegate EMS computation to secure hardware, ensuring sensitive operations occur in a protected environment.

If you want to know more about using callbacks in wolfSSL or 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

On May 12th, 2025, the test certificate baltimore-cybertrust-root.pem expired. This may cause issues with the test cases run during make check with wolfSSL builds that do not use the OpenSSL compatibility layer and have a filesystem enabled.

One of the unit tests attempts to load all Certificate Authorities (CAs) from the certs/external directory, which previously included this now-expired certificate. When this test is run with a wolfSSL configuration that will fail if any bad CAs are found among all CAs loaded, it will fail due to the certificate’s expiration.

This issue has been resolved in the wolfSSL master branch by the following pull request: https://github.com/wolfSSL/wolfssl/pull/8769

If you’re currently encountering failures during make check, we recommend removing the expired certificate from your local test environment by applying the changes from GitHub pull request 8769.

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

wolfSSL has extended its PKCS7 capabilities to better handle indefinite length encodings, particularly in streaming scenarios. While basic support for indefinite length verification existed, recent updates have refined the wc_PKCS7_VerifySignedData() API to process multipart and indefinite length content more efficiently in a streaming manner.(wolfSSL)

Key Enhancements

• Streaming Verification: The wc_PKCS7_VerifySignedData() function now supports verifying PKCS7 data with indefinite lengths without requiring the entire content to be buffered in memory.
• Improved Decoding: Enhancements in decoding functions allow for better handling of BER-encoded PKCS7 structures with indefinite lengths.

Example Usage

The wolfssl-examples repository provides practical demonstrations of these enhancements. For instance, the pkcs7-stream-verify example illustrates how to verify PKCS7 signed data in a streaming context:

PKCS7 pkcs7;
byte buffer[BUFFER_SIZE];
int ret;

// Initialize PKCS7 structure
wc_PKCS7_Init(&pkcs7, NULL, INVALID_DEVID);

// Set up certificate and key
pkcs7.cert = cert;
pkcs7.certSz = certSz;
pkcs7.privateKey = key;
pkcs7.privateKeySz = keySz;

// Begin streaming verification
ret = wc_PKCS7_VerifySignedData(&pkcs7, buffer, bufferSz);
if (ret != 0) {
    // Handle error
}

// Continue processing as needed

This approach allows applications to process and verify large or streaming PKCS7 data efficiently, without the need to load the entire content into memory.

Benefits

• Efficiency: Reduces memory usage by processing data in chunks.
• Flexibility: Supports a wider range of PKCS7 encoding scenarios, including those using indefinite lengths.
• Standards Compliance: Aligns with BER encoding standards for PKCS7 structures.(GitHub)

These enhancements make wolfSSL more adaptable for applications requiring secure, real-time data processing.

If you have questiona about any of the above, please contact us at facts@wolfSSL.com or call us at +1 425 245 8247.

Download wolfSSL Now

The NXP EdgeLock SE050 is a popular secure element providing a strong root of trust for IoT devices, known for its “Plug & Trust” simplicity. wolfSSL has consistently supported the SE050, enabling robust hardware-based security for TLS, cloud onboarding, and data protection. However, managing cryptographic keys on secure elements during development can often be a cumbersome task.
With the release of wolfSSL 5.8.0, we’re excited to introduce enhancements that significantly streamline the developer experience with the NXP SE050, most notably a new feature for automatic key deletion.

Simplifying Key Management with Automatic Key Deletion

During development and testing, developers frequently create and discard numerous cryptographic keys. On the SE050, these keys occupy persistent storage slots. Without careful manual cleanup, the keystore can quickly fill up, leading to errors and slowing down progress.
The Solution: WOLFSSL_SE050_AUTO_ERASE
A key improvement in wolfSSL 5.8.0. is the introduction of the WOLFSSL_SE050_AUTO_ERASE preprocessor define. When wolfSSL is compiled with this option, any key generated on or loaded into the SE050 via wolfSSL will be automatically erased from the secure element when the corresponding wolfCrypt key object in your application is freed (e.g., via wc_ecc_free()).
Benefits for Developers:

• Faster Iteration: Experiment freely without worrying about manual SE050 key cleanup.
• Simplified Testing: Automated tests that generate keys on the SE050 become more robust, as the risk of a full keystore is minimized.
• Reduced Clutter: Keeps the SE050 keystore clean from temporary development keys.
• Focus on Application Logic: Spend more time on your core application and less on SE050 housekeeping during development.

This feature is a significant quality-of-life improvement, making the powerful SE050 even more accessible, especially during rapid prototyping and testing phases.

Complementary SE050 Refinements

Alongside this key management enhancement, wolfSSL 5.8.0 also includes other refinements to our SE050 implementation. While the automatic key deletion is a highlight for developer workflow, these additional contributions are vital for the overall stability and performance of wolfSSL’s SE050 support, ensuring a polished and reliable experience.

Why These Enhancements Matter

These improvements in wolfSSL 5.8.0 underscore our commitment to providing security solutions that are not only robust but also developer-friendly. By reducing friction in the development process, we empower you to build secure applications more efficiently.

Getting Started

1. Download wolfSSL 5.8.0: Get the latest release from our download page.
2. Enable Automatic Key Deletion: Compile wolfSSL with the WOLFSSL_SE050_AUTO_ERASE define. For example, using autoconf: ./configure –with-se050 CFLAGS=”-DWOLFSSL_SE050_AUTO_ERASE” This is an opt-in feature, ideal for development and testing builds.
3. Consult Documentation: For full details on SE050 integration, refer to the README_SE050.md in the wolfSSL source (wolfcrypt/src/port/nxp/) and our examples in the wolfssl-examples repository.

Conclusion

The SE050 enhancements in wolfSSL 5.8.0, especially the automatic key deletion feature, make integrating hardware security with NXP’s SE050 smoother and more efficient. wolfSSL continues to provide cutting-edge security that is easy for developers to use.

• Explore the Code: Dive into the source code for these new SE050 enhancements on the wolfSSL GitHub repository: (https://github.com/wolfSSL/wolfssl).
• Contact Us: For questions, email us at facts@wolfssl.com or visit our support forums.

We’re excited for you to try these new features and experience a more streamlined SE050 development workflow!
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

Elliptic curve cryptography (ECC) is increasingly popular in secure communications, and secp256k1—famous for its use in Bitcoin and Blockchains—is a widely used curve. This blog post will walk you through building wolfSSL with support for secp256k1, generating an ECC certificate using that curve, and using it in a TLS connection with wolfSSL’s example client and server.

---

Step 1: Build wolfSSL with secp256k1 Support

Start by cloning the wolfSSL repository and building it with custom curve and certificate generation support:

# Download wolfssl from https://www.wolfssl.com/download/
cd wolfssl
./configure --enable-ecccustcurves=all --enable-keygen --enable-certgen --enable-certreq --enable-certext
make
sudo make install

---

Step 2: Generate a secp256k1 Certificate

Next, use the certgen example from wolfSSL’s examples repository.

git clone https://github.com/wolfssl/wolfssl-examples
cd wolfssl-examples/certgen

Modify the example for secp256k1

In certgen_example.c, modify the key generation line to explicitly use secp256k1:

- ret = wc_ecc_make_key(&rng, 32, &newKey);
+ ret = wc_ecc_make_key_ex(&rng, 32, &newKey, ECC_SECP256K1);

Add Key Output in PEM Format

To write the private key to a file, add the following block after certificate generation (be sure to add in proper error checks):

derBufSz = wc_EccKeyToDer(&newKey, derBuf, LARGE_TEMP_SZ);
pemBufSz = wc_DerToPem(derBuf, derBufSz, pemBuf, LARGE_TEMP_SZ, ECC_PRIVATEKEY_TYPE);
if (pemBufSz < 0) goto exit;

file = fopen("newCert.key", "wb");
if (!file) goto exit;
ret = (int)fwrite(pemBuf, 1, pemBufSz, file);
fclose(file);

Build and Run

make
./certgen_example

You should now have newCert.pem and newCert.key files using a secp256k1 key.

---

Step 3: Configure Client/Server for secp256k1

Go back to the wolfssl directory and modify the client example to explicitly support the secp256k1 curve:

+++ b/examples/client/client.c
@@ -3707,6 +3707,9 @@
     #endif
+
+    wolfSSL_CTX_UseSupportedCurve(ctx, WOLFSSL_ECC_SECP256K1);
+
 #if defined(HAVE_SUPPORTED_CURVES)

Run the Server and Client

Use the generated cert/key with the server, and run the client with a trusted CA cert:

./examples/server/server -d -c newCert.pem -k newCert.key

./examples/client/client -A ./certs/ca-ecc-cert.pem

If everything is set up correctly, you'll see output like:

SSL version is TLSv1.2
SSL cipher suite is TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
SSL curve name is SECP256K1
I hear you fa shizzle!

---

You’ve just built wolfSSL with support for custom ECC curves, generated a certificate using secp256k1, and successfully used it in a TLS session. This setup is great for anyone integrating Bitcoin-style cryptography into embedded or resource-constrained systems using wolfSSL.

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