Category: wolfSSL/ wolfCrypt

Expanding Cross-Compilation Capabilities in Visual Studio

With the recent release of wolfSSL, we have significantly improved the cross-compiling capabilities of wolfSSL in Visual Studio, particularly when targeting non-Windows operating systems from a Windows-based development environment. This improvement was introduced in PR #7884 and provides a new build option that makes cross-compilation smoother and more efficient.

Introducing WOLFSSL_NOT_WINDOWS_API

One of the key additions in this release is the new macro WOLFSSL_NOT_WINDOWS_API. This is specifically designed for scenarios where:

• The compilation is performed on Windows using Visual Studio.
• The target operating system is not Windows.
• The Windows API should not be used during compilation.

When WOLFSSL_NOT_WINDOWS_API is defined, the related macro USE_WINDOWS_API is not defined, ensuring that wolfSSL is built under the assumption that no Windows API functions are available. This allows developers to cross-compile for platforms such as Linux or embedded systems while using Visual Studio as their primary development environment.

Why is this Important?

In many embedded and IoT use cases, developers prefer to work within Visual Studio due to its powerful debugging and development tools. However, the final deployment target may be a non-Windows OS. Prior to this update, Visual Studio builds often assumed that Windows API functions were available, leading to compatibility issues when targeting platforms that do not support them.

With WOLFSSL_NOT_WINDOWS_API, these limitations are removed, making it much easier to:

• Compile wolfSSL for embedded Linux and other POSIX-based environments from Windows.
• Maintain a single development workflow without switching between build environments.
• Ensure consistent behavior across different platforms.

How to Use WOLFSSL_NOT_WINDOWS_API in Your Build

To leverage this new macro, follow these steps:

1. Modify Your Preprocessor Definitions:
   In your Visual Studio project settings, navigate to:
   • Configuration Properties → C/C++ → Preprocessor → Preprocessor Definitions
   • Add WOLFSSL_NOT_WINDOWS_API to the list.
2. Use CMake (if applicable):
   If you are using CMake for your build configuration, you can define this macro using:

   add_definitions(-DWOLFSSL_NOT_WINDOWS_API)

3. Manually Define in Your Code (not recommended):
   You can also define the macro at the beginning of your source files, though this is not the preferred method:

   #define WOLFSSL_NOT_WINDOWS_API
   #include 
   #include 
   

Example Use Case: Building wolfSSL for Linux from Visual Studio

Let’s say you want to compile wolfSSL in Visual Studio for a Linux-based target while avoiding Windows API dependencies. Here’s a step-by-step approach:

1. Set Up Your Toolchain
   Install a cross-compilation toolchain for Linux, such as MinGW-w64 or WSL with a Linux cross-compiler.
2. Update Your Visual Studio Project Settings
   • Define WOLFSSL_NOT_WINDOWS_API in preprocessor definitions.
   • Ensure that your include paths point to the correct non-Windows headers.
3. Compile and Verify
   • Build the project in Visual Studio.
   • Test the generated binary on the target Linux system to ensure it operates correctly.

Future Enhancements and Next Steps

This update is just the beginning of improving wolfSSL’s cross-compilation capabilities within Visual Studio. Some potential future enhancements include:

• Better integration with CMake toolchains for automated cross-platform builds.
• Expanded CI/CD support for Visual Studio-based cross-compilation.
• Additional optimizations to streamline the build process further.

Conclusion

With the introduction of WOLFSSL_NOT_WINDOWS_API, developers can now cross-compile wolfSSL in Visual Studio for non-Windows targets without encountering Windows API dependencies. This simplifies the workflow for embedded and Linux developers who prefer to work in Visual Studio but deploy on other platforms.

For more details on getting started with wolfSSL in Visual Studio, check out our previous blog: Getting Started with wolfSSL Using Visual Studio 2022

Or this awesome webinar recording on YouTube.

Have a specific request or questions? We’d love to hear from you. Please contact us at support@wolfSSL.com or open an issue on GitHub.

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

Download wolfSSL Now

Here at wolfSSL, we love making top notch examples for our customers to help them move faster. You can see a huge sample of them here.

That said, this one is a bit different. This is an example of how someone could integrate their new RNG into our wolfCrypt library. Here are some great reasons why you’d want to do that:

• You might have a NIST-certified entropy source which would be helpful for a customer that has FIPS 140-3 requirements. Since wolfSSL is FIPS 140-3 certified, combining it with a NIST-certified entropy source is a natural fit.
• Perhaps you have a special new RNG but do not have the man-power nor expertise to construct a cryptographic library to use it. (Rule #1: Never roll your own crypto!) In this case, integrating it with wolfSSL’s wolfCrypt library is a natural match to show real world use cases. Examples of this might be QRNGs (Quantum Random Number Generators) or any other new and interesting entropy generation methods.

Integrating your product into wolfCrypt might sound difficult, but it is NOT!

We show how easy it is by integrating a toy example of an RNG. Please see the patch that can be found as a github gist.

It is called the DEADBEEF RNG because when it is called to fill a buffer with randomness, it fills it with copies of 0xDEADBEEF. The diff is only 200 lines and is very simple to read and understand. Much of it is GPL boilerplate comments.

NOTE: Please do not use this patch. It is for illustrative purposes only! It provides zero randomness!

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

Download wolfSSL Now

The team at wolfSSL has taken the core functionality of the wolfSSL embedded SSL/TLS library to the next level and implemented changes to conform to the Required and Mandatory rules from the MISRA-C guidelines.

Currently a subset of the wolfCrypt modules are already covered for compliance, including detailed deviation documents (sha256.c, aes.c (CBC/GCM), rsa.c, random.c, sp_c64.c). Let us know if your project requires other files and we can target them while expanding coverage.

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

Download wolfSSL Now

wolfSSL is continuously improving its support for DTLS (Datagram Transport Layer Security) to make it easier for developers to handle connection IDs and implement stateless DTLS services. In this blog post, we’ll explore the new APIs introduced in wolfSSL 5.7.6 that simplify these tasks.

DTLS is a variant of TLS designed for datagram-based transports like UDP. It’s widely used in IoT and real-time applications where packet loss and reordering are common. Connection IDs allow to tag each connection so that they can be maintained despite network changes, reducing rehandshake frequency and enhancing security with features like encrypted record types and padding for privacy. The wolfSSL stack allows the server to establish new connections in a stateless manner by not allocating any extra resources until the client can prove that they can reply to server packets. Managing CIDs and stateless operations can be challenging, but wolfSSL has introduced new features to streamline this process.

Demultiplexing DTLS messages for a server involves distinguishing between multiple client connections using a single socket. When data arrives on the socket, the server reads the packet and extracts the source IP address, port, and the connection ID. This information is then used to search through a list of active connections, matching the incoming packet’s source details with existing connections. The matching is done either based on the source address of the received datagram or on the CID found in the message itself. If a match is found, the data is processed by that connection. If no match is found, it attempts to establish a new connection. This method ensures each packet is correctly routed to its respective connection, allowing multiple clients to communicate over a single socket efficiently without dropping any packet.

wolfDTLS_accept_stateless

This function allows accepting DTLS connections in a stateless manner. It’s designed to use a single WOLFSSL object to listen to all new connections and indicate to the user when the WOLFSSL object has entered stateful handling and should no longer be used for new connections.

Example:

WOLFSSL* ssl;

do {
rc = wolfDTLS_accept_stateless(ssl);
if (rc == WOLFSSL_FATAL_ERROR) {
        	/* re-allocate the ssl object with wolfSSL_free() and wolfSSL_new() */
	}
} while (rc != WOLFSSL_SUCCESS);
rc = wolfSSL_accept(ssl);
if (rc != SSL_SUCCESS) {
	/* Handle error */
}

wolfSSL_inject

The `wolfSSL_inject` function allows you to inject application data directly into the WOLFSSL object, bypassing the usual IO calls. This is useful when data needs to be read from a single place and demultiplexed into multiple connections. The caller should then call wolfSSL_read() to extract the plaintext data from the WOLFSSL object.

Example:

int rc;
WOLFSSL* ssl;
byte data[2000];

sz = recv(fd, data, sizeof(data), 0);
if (sz <= 0) {
	/* Handle error */
}

/* Inject received data */
rc = wolfSSL_inject(ssl, data, sz);
if (rc != WOLFSSL_SUCCESS) {
	/* Handle error */
}

wolfSSL_dtls_set_pending_peer

This function is introduced to handle the peer address when using Connection IDs. It sets a pending peer that will be upgraded to a regular peer when the next record is successfully de-protected. This should be used with Connection ID's to allow seamless and safe transition to a new peer address. This function can be called for every incoming datagram or when an address change is detected.

Example:

WOLFSSL* ssl;
sockaddr_in addr;

rc = wolfSSL_dtls_set_pending_peer(ssl, &addr, sizeof(addr));
if (rc != WOLFSSL_SUCCESS) {
	/* Handle error */
}

wolfSSL_is_stateful

This function checks if the current SSL session is stateful. This can be useful for determining whether the listening WOLFSSL object is still waiting to be associated with a single peer or if it has already progressed to handling a single connection.

Example:

WOLFSSL* ssl;
byte isStateful;

rc = wolfSSL_accept(ssl);
/* rc might indicate failure when using non-blocking sockets */

if (wolfSSL_is_stateful(ssl)) {
	/* Session is stateful */
} else {
	/* Session is stateless */
}

wolfSSL_dtls_cid_parse

This function parses a CID from a DTLS message. This is useful for extracting and handling connection IDs in your application.

Example:

WOLFSSL* ssl;
/* DTLS 1.2 app data containing CID */
byte cid12[] =
"\x19\xfe\xfd\x00\x01\x00\x00\x00\x00\x00\x01\x77\xa3\x79\x34\xb3" \
"\xf1\x1f\x34\x00\x1f\xdb\x8c\x28\x25\x9f\xe1\x02\x26\x77\x1c\x3a" \
"\x50\x1b\x50\x99\xd0\xb5\x20\xd8\x2c\x2e\xaa\x36\x36\xe0\xb7\xb7" \
"\xf7\x7d\xff\xb0";
size_t cid_len = 8;

const unsigned char* cid = wolfSSL_dtls_cid_parse(cid12, sizeof(cid12), cid_len);
if (cid == NULL) {
	/* Handle missing CID */
}

wolfSSL_SSLDisableRead and wolfSSL_SSLEnableRead

These functions allow you to control the reading of data from the IO layer. `wolfSSL_SSLDisableRead` disables read operations, while `wolfSSL_SSLEnableRead` re-enables them.

Example:

WOLFSSL* ssl;

/* Disable reading */
wolfSSL_SSLDisableRead(ssl);

/* Perform some operations */

/* Re-enable reading */
wolfSSL_SSLEnableRead(ssl);

These new APIs in wolfSSL make handling DTLS connection IDs and implementing stateless services easier and more efficient. By providing direct data injection, pending peer management, state checks, and read control, wolfSSL continues to enhance its support for secure datagram-based communications. For more information about new and existing API visit our manual and take a look at our examples.

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

Download wolfSSL Now

The wolfSSL team is announcing the deprecation of the ARC4 cipher. This decision is part of our ongoing effort to simplify the wolfSSL codebase and focus on supporting the most secure and widely-used ciphers.

The ARC4 cipher has been shown to have significant weaknesses, including:

• Key biases and correlations
• Plaintext recovery attacks
• Increased risk of data breaches

Removing ARC4 will allow us to reduce the complexity of our codebase and devote more resources to maintaining and improving our supported ciphers.

Recommendations:

• Begin transitioning away from ARC4 and towards more secure ciphers, such as AES or ChaCha20.
• Consult the wolfSSL documentation and support resources for guidance on migrating away from ARC4.

We will provide additional information on the removal timeline in the future. If you have any questions or concerns about this deprecation, please don’t hesitate to reach out to the wolfSSL support team.

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

Download wolfSSL Now

In today’s digital landscape, the need for robust authentication mechanisms has never been more crucial. Among the various methods available, SPAKE (Simple Password-Authenticated Key Exchange) stands out as an enhanced security solution for authenticating users.

SPAKE represents a significant advancement over traditional password-based authentication, which often relies on static hashes. By leveraging a shared secret key, SPAKE ensures that passwords are never directly exposed during the authentication process, thereby mitigating risks associated with compromised credential storage.

The integration of wolfSSL into the Kerberos 5 implementation further elevates security by providing FIPS 140-3 certified cryptography. This compliance ensures that cryptographic modules meet stringent security standards, crucial for organizations prioritizing data protection and regulatory adherence.

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

Download wolfSSL Now

Ladies and gentlemen, it’s story time!!

Once upon a time, there was a network administrator that only wanted to use the strongest NIST-approved ECC encryption available within the TLS 1.3 protocol. They picked ECDHE over the secp521r1 curve. When they went to code their application, they wanted the best TLS library available so they naturally picked wolfssl.

In order to let their peers know that they wanted to use ECDHE over the secp521r1 curve with TLS 1.3, they used the wolfSSL_UseKeyShare() API during the setup of the connection. With this addition they thought they were done. Like any good software developer, they then tested their application against many servers and found that it worked as expected. Happy with the results, our security conscious network administrator began using their new application.

A little while later, during a network security audit, the consultant found that the application was on some occasions using ECDHE over the secp256r1 curve!! Flabbergasted, the network administrator demanded proof and the consultant showed him the wireshark transcripts. Low and behold, the transcripts showed that the server had sent a HelloRetryRequest handshake message requesting secp256r1. This was because the SupportedGroups extension in the ClientHello had advertised support for secp256r1 and that was the only curve that this particular server supported.

In the end, the solution was simple. Our network administrator called wolfSSL_set_groups() specifying only secp521r1. The next time he connected to the offending server, it simply refused the connection. Then our administrator upgraded that server to support secp521r1. Our hero and their application and servers lived happily ever after.

– The End –

Note this parable does not constitute a bug nor vulnerability in the wolfssl library. What happened was exactly how TLS 1.3 is supposed to work. This is a case of unintended consequences due to insufficient configuration.

Another possible more bullet proof solution is to compile out support for weaker ECC curves during the configuration of the wolfssl library.

This parable is especially relevant in the era of post-quantum cryptography. If you are trying to thwart the “harvest now, decrypt later” threat model and you are willing to sacrifice some interoperability, then you do not want to advertise support for conventional algorithms.

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

Download wolfSSL Now

As part of our ongoing effort to maintain the highest level of security and performance, we are announcing the upcoming deprecation of RC2 from wolfCrypt. All of our products depend on wolfCrypt for their algorithm implementations so this could have consequences across our whole product line.

What is RC2?

RC2 is a symmetric-key block cipher that was widely used in the past for data encryption. Developed in 1987 by Ron Rivest, RC2 is now over 35 years old.

Why is RC2 being deprecated?

The main reasons for deprecating RC2 are:

• Security vulnerabilities: RC2 has been shown to be vulnerable to certain attacks, such as brute-force attacks and side-channel attacks.
• Limited key size: RC2’s key size is limited to 64 bits, which is considered too small for modern cryptographic purposes.
• Better alternatives available: TLS 1.3 forbids RC2 and now there are more secure and efficient cryptographic algorithms available, such as AES and ChaCha20.
• Regulatory requirements: The NSA has made it clear, RC2 is now obsolete. Learn more

What does this mean for our users?

We will soon be deprecating RC2 in our products and services. This means that:

• New versions of wolfCrypt: RC2 will no longer be available in future version of wolfCrypt. Are you using protocols that require RC2? Does this break compatibility with peers you communicate with? Let us know by sending a message to support@wolfssl.com
• Existing deployments: We will provide a transition period for existing deployments to migrate to a more secure algorithm.
• Support: We will no longer provide support for RC2-related issues, but we will make suggestions to help ease your transition.

What are the recommended alternatives?

We recommend using more secure and efficient cryptographic algorithms, such as:

• AES: A widely used and highly secure symmetric-key block cipher.
• ChaCha20: A fast and secure stream cipher.

We encourage our users to start planning their migration to a more secure algorithm as soon as possible.

If you have any questions or concerns, please don’t hesitate to reach out to facts@wolfSSL.com or call us at +1 425 245 8247.

Download wolfSSL Now

STMicroelectronics recently released a new range of ARM based MPUs. These are industrial grade ARM microprocessors that provide excellent performance as well as many useful features. ST have released OpenSTLinux to run on these chips, but they have also made a version of their bare-metal HAL API which works with these chips.

The wolfSSL team has recently ported wolfSSL to bare metal for the STM32MP135F in this range. This chip has a single-core 1GHz ARM Cortex-A7 which has hardware crypto acceleration features. There have been multiple parts to this work, which I will walk through in this post.

HAL porting

The previous AES, HASH and PKA HAL acceleration for STM32 MCUs has been ported to work with the STM32MP13 HAL. Every hardware acceleration feature we have previously supported for STM32 MCUs works with this MPU.

During testing, we clocked the MPU at 650MHz, which is the default high clock speed for bare-metal. At this speed we can get 12MB/sec AES-CBC, 9MB/sec AES-GCM and 90MB/sec SHA256. This is with the core clocked at only 65% of its maximum speed.

Extra hash support

We didn’t just stop there: we also added HAL acceleration for additional SHA types. With this MPU, we can now accelerate SHA-384, SHA-512 and SHA3 types. All also achieving around 85-90MB/sec. This is a 10-30x improvement over what you would typically see when running software-based algorithms for these types on the same hardware.

All the work we did to add these hash types should be easily portable to ST MCUs that support those types in the HAL. You can email us at support@wolfSSL.com if you wish for us to assist you with this porting work.

wolfSSL Example

Setting up and running the MPU in bare-metal mode can be a little bit tricky, so on top of all of this, we created a documented example so that you can create an echo client. This example is designed to be used with the STM32MP135F-DK development board. It uses FreeRTOS and LwIP, so it can be extended to do other things.

The example is available on our wolfssl-examples-stm32 GitHub repository.

There is also a README available in the main wolfSSL source tree, which can guide you through using wolfCrypt with the STM32MP135F.

What about Linux?

For those who want to use OpenSTLinux, wolfSSL “just works”. Using ST’s cross-compile toolchain, you can compile wolfSSL just like you would for any other Linux installation. On Linux, this is the wolfCrypt benchmark results:

------------------------------------------------------------------------------
 wolfSSL version 5.7.4
------------------------------------------------------------------------------
Math:   Multi-Precision: Wolf(SP) word-size=32 bits=4096 sp_int.c
        Single Precision: ecc 256 384 rsa/dh 2048 3072 4096 asm sp_cortexm.c
wolfCrypt Benchmark (block bytes 1048576, min 1.0 sec each)
RNG                         10 MiB took 1.049 seconds,    9.537 MiB/s
AES-128-CBC-enc             20 MiB took 1.003 seconds,   19.931 MiB/s
AES-128-CBC-dec             20 MiB took 1.075 seconds,   18.597 MiB/s
AES-192-CBC-enc             20 MiB took 1.198 seconds,   16.697 MiB/s
AES-192-CBC-dec             20 MiB took 1.254 seconds,   15.947 MiB/s
AES-256-CBC-enc             15 MiB took 1.063 seconds,   14.105 MiB/s
AES-256-CBC-dec             15 MiB took 1.076 seconds,   13.943 MiB/s
AES-128-GCM-enc             10 MiB took 1.044 seconds,    9.577 MiB/s
AES-128-GCM-dec             10 MiB took 1.018 seconds,    9.822 MiB/s
AES-192-GCM-enc             10 MiB took 1.130 seconds,    8.846 MiB/s
AES-192-GCM-dec             10 MiB took 1.128 seconds,    8.867 MiB/s
AES-256-GCM-enc             10 MiB took 1.191 seconds,    8.393 MiB/s
AES-256-GCM-dec             10 MiB took 1.204 seconds,    8.307 MiB/s
GMAC Table 4-bit            20 MiB took 1.014 seconds,   19.716 MiB/s
CHACHA                      35 MiB took 1.102 seconds,   31.750 MiB/s
CHA-POLY                    30 MiB took 1.173 seconds,   25.586 MiB/s
POLY1305                   120 MiB took 1.027 seconds,  116.896 MiB/s
SHA                         45 MiB took 1.029 seconds,   43.727 MiB/s
SHA-256                     25 MiB took 1.042 seconds,   23.988 MiB/s
HMAC-SHA                    45 MiB took 1.075 seconds,   41.845 MiB/s
HMAC-SHA256                 25 MiB took 1.029 seconds,   24.291 MiB/s
RSA     2048   public      1400 ops took 1.043 sec, avg 0.745 ms, 1342.619 ops/sec
RSA     2048  private       100 ops took 2.532 sec, avg 25.324 ms, 39.488 ops/sec
DH      2048  key gen        86 ops took 1.007 sec, avg 11.707 ms, 85.419 ops/sec
DH      2048    agree       100 ops took 1.194 sec, avg 11.939 ms, 83.763 ops/sec
ECC   [      SECP256R1]   256  key gen      1500 ops took 1.023 sec, avg 0.682 ms, 1466.898 ops/sec
ECDHE [      SECP256R1]   256    agree       700 ops took 1.037 sec, avg 1.482 ms, 674.714 ops/sec
ECDSA [      SECP256R1]   256     sign      1200 ops took 1.109 sec, avg 0.924 ms, 1081.961 ops/sec
ECDSA [      SECP256R1]   256   verify       700 ops took 1.146 sec, avg 1.638 ms, 610.589 ops/sec

Details on this can also be found in the wolfSSL STM32MP13 README.

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

Download wolfSSL Now