RECENT BLOG NEWS

Recently the question of building the wolfCrypt test and benchmark applications in a non-standard environment has been asked multiple times to our support team. We wanted to provide a solution for those who might be struggling!  The wolfSSL embedded SSL/TLS library ships with both of these applications to help users get up and running on their platform with wolfSSL.

The wolfCrypt test application runs algorithm tests on all enabled algorithms to verify they are working correctly on your platform.  This should be the first step taken when porting wolfSSL to a new platform.

The wolfCrypt benchmark application benchmarks cryptography algorithms enabled in wolfSSL.  This gives users an idea of the cryptography library performance for their specific platform and configuration.  This can also be helpful for seeing the performance difference in using software cryptography versus hardware cryptography.

To start let’s cover how you would call the wolfCrypt test or benchmark from your application.

typedef struct func_args {
 int argc;
 char** argv;
 int return_code;
} func_args;


/* ... other code ... */

int main (void)
{
    /* other function declarations */
    func_args args;

    /* ... system setup and initialization ... */

    /* for wolfcrypt test app: */
    ret = wolfcrypt_test(&args);

    /* for benchmark app: */
    /* ret = benchmark_test(&args); */

    if (ret != 0) {
        printf("wolfCrypt tests failed!\n")
        printf("test returned error code: %d\n", ret);
        printf("the crypto error code was: %d\n", args.return_code);
    } else {
        printf("crypto tests PASSED!\n");
    }

    while (1)
    {
        /* Application code TODO: Logic here */
    }
}

In addition to the porting and tuning guides found at the links below, there may be some other items to add to your settings before the wolfCrypt tests or benchmark will run.

wolfSSL Porting Guide
wolfSSL Tuning Guide

Items not covered in the porting and tuning guide include:

• NO_MAIN_DRIVER
• BENCH_EMBEDDED
• NO_64BIT
• USE_CERT_BUFFERS_XXX(X)
• ALT_ECC_SIZE
• ECC_USER_CURVES (and related defines)
• FP_MAX_BITS.

And while the fastmath vs normal math libraries are covered, we wanted to expand on that explanation here, highlighting the difference between fastmath (uses more stack and less heap) versus the normal math library (uses more heap and less stack).

Please feel free to use these defines as a starting point when porting the wolfCrypt test application (<wolfssl-root>/wolcrypt/test/test.c) and wolfCrypt benchmark application (<wolfssl-root>/wolfcrypt/benchmark/benchmark.c) to your non-standard environment!

/* Other defines as determined from the wolfSSL porting guide found here:
 * https://wolfssl.com/wolfSSL/Docs-wolfssl-porting-guide.html
 */

/* Purpose: 
 * If running the wolfcrypt/benchmark/benchmark.c
 * app will reduce stack use for embedded devices
 */
#define BENCH_EMBEDDED

/* Purpose:
 * Embedded systems already have a main method typically
 * will remove the "main" in benchmark.c and test.c
 */
#define NO_MAIN_DRIVER

/* Purpose:
 * If working on a 32-bit system, it will sometimes use 2x 32-bit types to execute 64-bit
 * math operations which greatly slows down computation time. This define can speeds
 * things up. Commented by default, uncomment if computation speeds are too slow.
 */
/* #define NO_64BIT */

/* Begin RSA Section */
/* --------------------------------------------------- */

/* Uncomment the define for NO_RSA to remove RSA */
/* #define NO_RSA */

#ifndef NO_RSA
    #error "Please set RSA key size then comment out or delete this line."
    /* XXXX should be "2048" for 2048 bit RSA keys
     * XXXX should be "1024" for 1024 bit RSA keys
     * IE choose one of the following to uncomment
     */
 
    /* #define USE_CERT_BUFFERS_2048 */
    /* #define USE_CERT_BUFFERS_1024 */

    /*
     * the certificate buffers can be found in <wolfssl-root>/wolfssl/test_certs.h
     */

    /* Purpose:
     * To reduce stack based on RSA key size chosen
     */
    #ifdef USE_CERT_BUFFERS_1024
        #define FP_MAX_BITS 2048 /* (RSA key size selected x2) */
    #elif defined(USE_CERT_BUFFERS_2048)
        #define FP_MAX_BITS 4096
    #endif /* USE_CERT_BUFFERS_1024 */
#endif /* NO_RSA */

/* --------------------------------------------------- */
/* End File System and RSA section */

/* Begin ECC Section */
/* --------------------------------------------------- */

/* Purpose:
 * enable ECC. Comment to remove ECC
 */
#define HAVE_ECC

#ifdef HAVE_ECC
    #define ECC_TIMING_RESISTANT /* See explenation for TFM_TIMING_RESISTANT */
    #define USE_CERT_BUFFERS_256 /* for ecc, see File System and RSA Section above */

    /* the certificate buffers can be found in <wolfssl-root>/wolfssl/test_certs.h

    /* Purpose:
     * Reduce ECC memory use
     */
    #define ALT_ECC_SIZE

    /* Purpose:
     * Only allow for 256-bit ecc keys by default. To remove support for 256-bit ECC keys
     * uncomment the next line.
     */
    /* #define NO_ECC256 */
 
    /*
     * A list of supported ECC curves is included below, uncomment as desired.
     * For other ECC defines see <wolfssl-root>/wolfcrypt/src/ecc.c
     */
    #define ECC_USER_CURVES

    /* #define HAVE_ECC112 */
    /* #define HAVE_ECC128 */
    /* #define HAVE_ECC160 */
    /* #define HAVE_ECC192 */
    /* #define HAVE_ECC224 */
    /* #define HAVE_ECC239 */
    /* #define HAVE_ECC320 */
    /* #define HAVE_ECC384 */
    /* #define HAVE_ECC512 */
    /* #define HAVE_ECC521 */

#endif /* HAVE_ECC */
/* --------------------------------------------------- */
/* End ECC Section */

If you have any other questions or comments on this or anything else please contact us!

support@wolfssl.com
facts@wolfssl.com

Providing Secure, Well-Tested SGX Integration with wolfSSL and wolfCrypt

Did you know that wolfSSL has support for Intel SGX?  Not only do we have support for SGX, but we do continuous integration testing on that support to offer our users a more robust and mature solution. This means that every night a process starts up and runs unit tests on crypto operations in a secure SGX enclave. Here’s a peek at some of the on going tests in action:

…
LINK => App
GEN => trusted/Wolfssl_Enclave_t.c
CC <= trusted/Wolfssl_Enclave_t.c
cc -Wno-implicit-function-declaration -std=c11 -m64 -O2 -nostdinc -fvisibility=hidden -fpie -fstack-protector -IInclude -Itrusted -I../..// -I../..//wolfcrypt/ -I/opt/intel/sgxsdk/include -I/opt/intel/sgxsdk/include/tlibc -I/opt/intel/sgxsdk/include/stlport-fno-builtin -fno-builtin-printf -I. -DWOLFSSL_SGX -DHAVE_WOLFSSL_TEST -c trusted/Wolfssl_Enclave.c -o trusted/Wolfssl_Enclave.o
CC <= trusted/Wolfssl_Enclave.c
-m64 -O2 -Wl,--no-undefined -nostdlib -nodefaultlibs -nostartfiles -L/opt/intel/sgxsdk/lib64 -L../../IDE/LINUX-SGX/ -lwolfssl.sgx.static.lib -Wl,--whole-archive -lsgx_trts -Wl,--no-whole-archive -Wl,--start-group -lsgx_tstdc -lsgx_tstdcxx -lsgx_tcrypto -lsgx_tservice -Wl,--end-group -Wl,-Bstatic -Wl,-Bsymbolic -Wl,--no-undefined -Wl,-pie,-eenclave_entry -Wl,--export-dynamic -Wl,--defsym,__ImageBase=0 -Wl,--version-script=trusted/Wolfssl_Enclave.lds@
LINK => Wolfssl_Enclave.so

…

SIGN => Wolfssl_Enclave.signed.so
+ ./App -t
Crypt Test:
error test passed!
base64 test passed!
base64 test passed!
MD5 test passed!
MD4 test passed!
SHA test passed!
SHA-256 test passed!
Hash test passed!
HMAC-MD5 test passed!
HMAC-SHA test passed!
HMAC-SHA256 test passed!
GMAC test passed!
ARC4 test passed!
HC-128 test passed!
Rabbit test passed!
DES test passed!
DES3 test passed!
AES test passed!
AES192 test passed!
AES256 test passed!
AES-GCM test passed!
RANDOM test passed!
RSA test passed!
DH test passed!
DSA test passed!
PWDBASED test passed!
ECC test passed!
ECC buffer test passed!
mutex test passed!
memcb test passed!
Crypt Test: Return code 0
…

If you are interested in using wolfSSL or wolfCrypt inside a secure Intel SGX enclave, let us know at facts@wolfssl.com.  We can provide you with full details of our current support and evaluation information.  We can also help answer questions about users interested in FIPS 140-2 cryptography support inside an SGX enclave environment.

Curious about why wolfSSL is the most well-tested SSL/TLS library available today?  Get the details here!

In this past (here and here) we have written about wolfSSL’s I/O abstraction layer and support for alternative I/O mediums.  We wanted to refresh our reader’s memory about this helpful feature.  In this context, “less traditional I/O” means running SSL/TLS over something besides TCP/IP or UDP – for example Bluetooth, a serial connection, memory buffers, or a proprietary transfer protocol.  In embedded projects looking for a lightweight TLS solution, we know this can be common.

wolfSSL I/O Abstraction Layer

wolfSSL provides a mechanism to plug in your own application-specific I/O routines. By default, the library calls a BSD socket API, with functions that call the system’s recv() and send() using a file descriptor that has been cached with wolfSSL_set_fd().

The prototypes for the I/O callback functions are:

typedef int (*CallbackIORecv)(WOLFSSL *ssl, char *buf, int sz, void *ctx);
typedef int (*CallbackIOSend)(WOLFSSL *ssl, char *buf, int sz, void *ctx);

In the default case, the network socket’s file descriptor is passed to the I/O callback in the “ctx” parameter. The “ssl” parameter is a pointer to the current wolfSSL session, giving callbacks access to session-level details if needed.

In the receive case, “buf” points to the buffer where incoming ciphertext should be copied for wolfSSL to decrypt and “sz” is the size of the buffer. Callbacks should copy “sz” bytes into “buf”, or the number of bytes available.  In the send case, “buf” points to the buffer where wolfSSL has written ciphertext to be sent and “sz” is the size of that buffer.  Callbacks should send “sz” bytes from “buf” across their transport medium.  In either case the number of bytes written or read should be returned, or alternatively an applicable error code.

To register your own I/O callbacks with the WOLFSSL_CTX, use the functions wolfSSL_SetIORecv() and wolfSSL_SetIOSend().

wolfSSL_SetIORecv(ctx, myCBIORecv);
wolfSSL_SetIOSend(ctx, myCBIOSend);

A Simple Example using Memory Buffers

Oftentimes walking through a simple example helps make this more understandable.  One example use case for alternative I/O is a server that receives data from multiple clients or processes TLS through STDIN and STDOUT. In this application there could be four buffers:

• cipher-receive     encrypted data received from peer
• cipher-send         encrypted data to be sent to peer
• clear-receive       clear data received from wolfSSL
• clear-send           clear data passed to wolfSSL

Pointers to these buffers, values for their sizes, and read and write positions can be placed into a user-defined structure. A pointer to this structure would then be cached in the wolfSSL session with the functions wolfSSL_SetIOReadCtx() and wolfSSL_SetIOWriteCtx().

wolfSSL_SetIOReadCtx(ssl, buffer_data);
wolfSSL_SetIOWriteCtx(ssl, buffer_data);

The application would receive a block of ciphertext into the buffer “cipher-receive”, and call wolfSSL_read(ssl, buffer_data->clear_receive), causing wolfSSL to call the registered receive callback. The receive callback will be given a buffer, the size of the buffer, and the context (ctx), which contains the “cipher-receive” buffer. The callback might be called many times internally for a single call to wolfSSL_read(). If the “cipher-receive” buffer is empty, the callback will return -2 (WOLFSSL_CBIO_ERR_WANT_READ), otherwise it will return the number of bytes copied into “buf”.  WOLFSSL_CBIO_ERR_WANT_READ is an error condition that indicates that there was no data available for reading at the time that the callback requested data.  In this case, the application should loop back around and make the high-level API call (wolfSSL_read(), wolfSSL_connect(), etc) again when data is ready to be read.

When the library wants to send data, during handshaking or when wolfSSL_send() is called with plaintext, the library will call the registered send callback. The callback is given a buffer full of encrypted data, and the length of the encrypted data. In this example, the callback would copy this cipher text into “cipher-send” and return the number of bytes copied. If the “cipher-send” buffer isn’t big enough, the callback should return -2 (WOLFSSL_CBIO_ERR_WANT_WRITE).

Additional Resources

If you are interested in looking over an example of using the wolfSSL I/O abstraction layer, we have an example client/server application at the following link that does TLS using files as the transport medium.  Please feel free to contact us at facts@wolfssl.com with any further questions about using the wolfSSL lightweight TLS library.

https://github.com/wolfSSL/wolfssl-examples/tree/master/custom-io-callbacks

MySQL (#mysql) currently comes bundled with yaSSL to provide an option for SSL/TLS connections when using a database. A patch for securing MySQL with the wolfSSL embedded TLS/SSL library is available for MySQL version 8.0.0 here https://github.com/wolfSSL/mysql-patch.

Along with an increased level of security comes the potential to use progressive features offered by wolfSSL – such as TLS 1.3 and ChaCha20 / Poly1305 AEAD cipher suites (ex: ECDHE-RSA-CHACHA20-POLY1305). Another great feature is that wolfSSL cryptography is FIPS 140-2 validated! The change from yaSSL to wolfSSL will fit nicely into both Open Source and commercial applications, as it is dual licensed under both GPLv2 and standard commercial license terms.

For more information about the port contact us at facts@wolfssl.com

wolfSSH v1.2.0 has dropped! We have just added support for Elliptic Curve algorithms and AES-GCM. The following key exchange and public key algorithms are now available:

• ecdh-sha2-nistp256
• ecdh-sha2-nistp384
• ecdh-sha2-nistp521
• ecdsa-sha2-nistp256
• ecdsa-sha2-nistp384
• ecdsa-sha2-nistp521

The wolfSSH SSH server provides the encryption algorithm “aes128-gcm@openssh.com”, which is an implementation of RFC 5647 using the MAC algorithm implied with using the AEAD algorithm AES-GCM. The wolfSSH library provides the messages for including in a client application. Also included is a build solution for MS Visual Studio.

wolfSSH v1.2.0 works best with wolfCrypt v3.12.2. The wolfCrypt/wolfSSL configure script has a wolfSSH enable option to simplify building. Download wolfSSH from the wolfSSL download page today!

STARTTLS is a way of protecting email communications from malicious users (insiders or otherwise) by upgrading a plaintext SMTP connection to one secured by SSL/TLS.  SMTP using STARTTLS allows encryption of emails in transit between email clients and servers. Without encryption email messages can easily be intercepted and read at any point between the sender and the receiver.

wolfSSL has had multiple inquiries about STARTTLS and how to use wolfSSL for the TLS encryption in this protocol. Due to the volume of inquiries over the past few months, we have added an example of using STARTTLS with wolfSSL to the wolfSSL example client. To try it out download wolfSSL from the wolfSSL download page.

Instructions to build and run the examples included with the library can be found at:

Linux/Unix
Windows

Below is a quick example of connecting to GMail’s SMTP server with the wolfSSL example client.  This will open a plaintext communication, use STARTTLS to convert to a SSL/TLS-encrypted channel, then close the connection.

Linux/Unix: ./examples/client/client -h smtp.gmail.com -p 587 -M smtp -d
Windows: client.exe -h smtp.gmail.com -p 587 -M smtp -d

-h specifies the host server to connect to (smtp.gmail.com)
-p specifies the port to connect on (587 for email submission)
-M tells the example client to use STARTTLS with protocol (smtp in this case)
-d tells the client not to authenticate the peer
( to do peer authentication you can download Google’s CA and replace -d option with: “-A /path/to/google-CA”)

If you have any questions or comments please contact wolfSSL at facts@wolfssl.com or visit the wolfSSL support forums.

– The wolfSSL Team

A recent paper titled “Exploiting Dissent: Towards Fuzzing-based Differential Black-Box Testing of TLS Implementations” was published by Axel Sikora and Andreas Walz. wolfSSL found the paper both well composed and informative. We would like to congratulate Andreas and Axel on a well composed piece of literature and we would highly recommend reading it if you have the time!

This paper details a new differential testing method for fuzz testing and we will follow their research closely in the coming year. We hope to see more from Axel and Andreas soon. Until then, CHEERS and keep up the great work!

https://ivesk.hs-offenburg.de/fileadmin/Einrichtungen/ivesk/files/preprint_TLS-Diff-Fuzzing_IEEE-TDSC.pdf

If you have any questions, comments, or feedback please contact us anytime at support@wolfssl.com or facts@wolfssl.com

wolfSSL has a goal: “wolfSSL will provide the best security in the world for all to benefit”! We are very passionate about keeping our users safe and secure in an increasingly connected online world. To that end the wolfSSL product is the most thoroughly tested cryptography and TLS solution on the market today. wolfSSL appreciates and admires those who take the time and effort to implement tools that assist in making our goal a reality!

We recently were made aware of a tool being actively developed called “TLS-Attacker”. TLS-Attacker accomplishes “Systematic Fuzzing and Testing of TLS Libraries”.  This tool was developed by the Ruhr University Bochum and the Hackmanit GmbH . wolfSSL is evaluating this tool for integration with our Jenkins/Hudson continuous integration server and we wanted to give a “SHOUT OUT” to all the developers who worked on this or other similar fuzzing tools! Tools like this help to ensure secure SSL/TLS implementations and we look forward to working with TLS-Attacker. We want to say, “THANK YOU” to the Ruhr University Bochum staff and Hackmanit staff for their efforts!

For any questions, concerns or comments please contact us anytime at support@wolfssl.com or facts@wolfssl.com!

wolfSSL 3.12.2 is now available for download! This release includes many performance improvements with Intel ASM (AVX/AVX2) and AES-NI. wolfSSL has implemented a new single precision math option to speed up RSA, DH and ECC in this release. Embedded hardware support has been expanded for STM32, PIC32MZ and ATECC508A, and AES-XTS mode support has been added for use with disk encryption.

There have been improvements to some of our certificate API’s that allow for setting the serial number, key usage and extended key usage. A refactor of the `SSL_` API’s and hash types has been performed to allow OpenSSL coexistence. There have been improvements made for TLS 1.3 support in this release. A fix was implemented for OCSP stapling to prevent sending the extension unexpectedly, WOLFSSL specific user contexts were added for callbacks, and there were fixes for some OpenSSL and MySQL compatibility functions. The wolfSSL Micrium port was updated for Micrium uC/OS-III, and there were fixes implemented for asynchronous modes as well.

Continue reading below for a summary of the features and fixes included in this release!

General Improvements:

• Speedups for SHA2, ChaCha20/Poly1035 using AVX/AVX2
• Speedups for AES GCM with AES-NI (–enable-aesni)
• New Single Precision math option for RSA, DH and ECC (See –enable-sp) (all off by default).
• Math updates and added TFM_MIPS speedup
• Fixes for HAVE_INTEL_MULX
• Added AES XTS mode (–enable-xts)
• Rename the file io.h/io.c to wolfio.h/wolfio.c
• Cleanup the wolfIO_Send function
• Improvements to Visual Studio DLL project/solution
• Added function to generate public ECC key from private key
• Added async blocking support for sniffer tool
• Updated Micrium uC/OS-III Port

TLS v1.3:

• Fixes for various TLS 1.3 disable options (RSA, ECC and ED/Curve 25519)
• Fix to disallow upgrading to TLS v1.3
• Fixes for wolfSSL_EVP_CipherFinal() when message size is a round multiple of a block size
• Add HMAC benchmark and expanded AES key size benchmarks
• Added simple GCC ARM Makefile example (see IDE/GCC-ARM)
• Add tests for 3072-bit RSA and DH
• Fixed DRAFT_18 define and fixed downgrading with TLS v1.3

Certificates:

• Alternate certificate chain support with WOLFSSL_ALT_CERT_CHAINS defined enables checking a cert against multiple CA’s
• Fixes to allow custom serial number during certificate generation
• Added method to get WOLFSSL_CTX certificate manager
• Improvement to wolfSSL_SetOCSP_Cb to allow a context per WOLFSSL object
• Updated root certs for OCSP scripts
• Added ASN Extended Key Usage Support. (See wc_SetExtKeyUsage)
• Fix for creation of the KeyUsage BitString

Extensions:

• Added TLS extension for Supported Point Formats (ec_point_formats)
• Fix to not send OCSP stapling extensions in client_hello when not enabled

OCSP Stapling:

• Added new API’s for disabling OCSP stapling
• Add check for SIZEOF_LONG with Sun and LP64

Settings Updates:

• Added new –disable-oldnames option to allow for using openssl alongside wolfssl headers (without OPENSSL_EXTRA)
• Refactor SSL_ and hashing types to use wolf specific prefix (WOLFSSL and WC_) to allow OpenSSL coexistence
• Added configure option for building library for wolfSSH (–enable-wolfssh)
• Added ability to use wolf implementation of strtok using USE_WOLF_STRTOK

MySQL Support:

• Cleanup include paths for MySQL cmake build
• Fix for 8k keys with MySQL compatibility

OpenSSL compatibility:

• OpenSSL compatibility layer improvements, additions, and fixes

Testing:

• Expanded API unit tests
• Update HASH_DRBG Reseed mechanism and add test case
• Added wolfCrypt hash tests for empty string and large data

Hardware Support:

• Fixes for STM32 crypto hardware acceleration
• Fixes for ATECC508A
• Fixes for PIC32MZ hashing
• Fixes and improvements to asynchronous modes for Intel QuickAssist and Cavium Nitrox V

Team wolfSSL is preparing for Halloween with a pumpkin carving! Our embedded security products are continually evolving. We encourage you to check our our wolfSSL embedded SSL/TLS library here, wolfMQTT, wolfSSH, or visit our product page for a complete list of lightweight Open Source security products.

As always if you have any questions, or would like more information about our products, please contact us at facts@wolfssl.com.

Thanks,
Team wolfSSL