wolfSSL Getting Started for Yocto and OpenEmbedded

Introduction

wolfSSL maintains a Yocto and OpenEmbedded (OE) layer including recipes for wolfSSL products (wolfSSL, wolfSSH, wolfMQTT, wolfTPM), examples, and support for building other Open Source recipes with wolfSSL support. This layer is named “meta-wolfssl”, and is available on GitHub. This document will describe how to easily get started with wolfSSL for Yocto or OpenEmbedded.

meta-wolfssl:
https://www.github.com/wolfssl/meta-wolfssl

This layer includes recipes for:

  • wolfSSL embedded SSL/TLS library
  • wolfSSH lightweight SSH library
  • wolfMQTT lightweight MQTT Client Library
  • wolfTPM TPM 2.0 Library
  • wolfCrypt test application
  • wolfCrypt benchmark application
  • wolfSSL OpenSSH Recipe
  • cURL .bbappend file, for compiling cURL with wolfSSL support

The wolfSSL product recipe is also part of the “meta-openembedded/meta-networking/recipes-connectivity” layer, located here:

https://github.com/openembedded/meta-openembedded/tree/master/meta-networking/recipes-connectivity/wolfssl

wolfSSL Yocto has also been tested with the following versions of OpenEmbedded-Core :

  • sumo
  • thud
  • warrior
  • zeus
  • dunfell
  • hardknott
  • gatesgarth
  • kirkstone

Why use wolfSSL?

The wolfSSL embedded SSL/TLS library is a perfect fit for securing Yocto and OpenEmbedded based applications. wolfSSL has been optimized for low memory use and high performance, is extremely portable, supports current standards up to TLS 1.3 and DTLS 1.3, and can be easily combined with any of wolfSSL’s other products (SSH, MQTT, TPM, etc). wolfSSL also maintains a low CVE/vulnerability track record due to a thorough development and nightly testing cycle, providing users with the best tested cryptography available today.

wolfSSL is powered by the wolfCrypt library. A version of the wolfCrypt cryptography library has been FIPS 140-2 validated (Certificate #3389), with FIPS 140-3 validation currently in progress!

Getting Started

Environment, Build, and Image Setup

Adding the “meta-wolfssl” layer to your build, you will need to set up your development environment and image build directory. If you are an experienced Yocto/OE user, feel free to skip this section. If you need a good starting point, the Yocto Project provides a good Quick Build / Getting Started Guide.

Clone the "meta-wolfssl" Layer

You may want to place this alongside your other build layers for easy organization. In this guide, the example commands will assume your working Yocto/OE directory is located at “~/poky”. This is the directory that the Yocto Project Quick Build instructions use. Please change this to match your build directory.

$ cd ~/poky
$ git clone https://github.com/wolfssl/meta-wolfssl.git

Add “meta-wolfssl” to the Layer Configuration File

Insert the “meta-wolfssl” layer location into your build’s bblayers.conf file, in the BBLAYERS section:

BBLAYERS ?= " \
...
/path/to/yocto/poky/meta-wolfssl \
...
"

Add “meta-wolfssl” to Your Project

Edit your build’s local.conf file, adding the recipes from “meta-wolfssl” that you want to install and use in your project to the IMAGE_INSTALL_append variable. This will include and install the selected libraries.

For example, to install only the wolfSSL library:

IMAGE_INSTALL_append = "wolfssl"

To install wolfSSL, wolfSSH, wolfMQTT, and wolfTPM:

IMAGE_INSTALL_append = "wolfssl wolfssh wolfmqtt wolftpm"

To install wolfSSL and the wolfCrypt test and benchmark applications:

IMAGE_INSTALL_append = "wolfssl wolfcrypttest wolfcryptbenchmark"

Once your image has been built, the default location for the above libraries will be in the “/usr/lib” directory. The default location for the wolfCrypt test and benchmark applications will be in the “/usr/bin” directory.

Compiling “meta-wolfssl” Recipes Individually

Once the “meta-wolfssl” layer has been added to your BBLAYERS collection, you can build individual recipes from the layer using the bitbake command to make sure they compile successfully.

$ bitbake wolfssl
$ bitbake wolfcrypttest
$ bitbake wolfcryptbenchmark
$ bitbake wolfssh
$ bitbake wolfmqtt
$ bitbake wolftpm

Customizing the wolfSSL Library Build Configurations

The default wolfSSL product recipes are set up to compile the default library configurations. These default configurations are equivalent to running a normal “./configure” on the library if you were compiling it using the Autoconf tools. wolfSSL, and other libraries, have lots of available configure (enable/disable) options that can be used to customize the library feature set. Users commonly want to enable/disable features or algorithms to meet requirements, reduce memory usage, or optimize performance.

Finding and Viewing Library Configure Options

To see a list of available library configure options, either look at the product manual (ex: wolfSSL User Manual), or use the “./configure --help” command in the root of the wolfSSL library directory to list available configure options.

In order to have access to a library’s configure script, you need to be in the source directory of the product. You can either download the product from the wolfSSL website or browse to the temporary source directory that bitbake has created for you as part of the recipe build.

Using the temporary source directory created by the bitbake command, the configure help options could be viewed by running commands similar to below.

$ bitbake wolfssl
$ cd ~/poky/build/tmp/work/i586-poky-linux/wolfssl/X.XX.X-r0/wolfssl-X.XX.X               *
$ ./configure --help
…
--enable-blake2 Enable wolfSSL BLAKE2 support
--enable-sha512 Enable wolfSSL SHA-512 support
--enable-sha384 Enable wolfSSL SHA-384 support
…

*X.XX.X being the current version of the wolfSSL library

Now that you have found the list of possible enable options, the next step is to modify your build of the wolfSSL libraries to include the desired features.

Modifying Library Recipe Build to Include Additional Features

Although the library recipes can be edited directly, it is recommended that users create a .bbappend file in their application layers which override or edit desired wolfSSL library recipe configuration. This makes it easier to update when changes to the upstream “meta-wolfssl” layer get made.

For example, let’s say we have an application that wanted to use the wolfSSL library and needed SHA-512 support. To meet this requirement, the wolfSSL library recipe needs to be modified to compile in SHA-512 support (via the “--enable-sha512” configure option).

First, create a .bbappend file in the application layer which will append configuration information to the upstream wolfSSL recipe:

wolfssl_%.bbappend

Inside this .bbappend file, use the EXTRA_OECONF variable to add additional configure options to the wolfSSL library build. To enable SHA-512:

EXTRA_OECONF += “--enable-sha512”

Or, another example might be enabling support for TLS 1.3:

EXTRA_OECONF += “--enable-tls13”

Make Sure .bbappend Files Get Found by the Application

Depending on where the .bbappend file gets placed in your application layer, you may need to edit the BBFILES variable in your layer’s “conf/layer.conf” file to match the directory structure where the .bbappend file is located.

The BBFILES variable will be specific to your application layer’s structure. General structure may be similar to:

# We have a conf and classes directory, add to BBPATH
BBPATH := "${LAYERDIR}:${BBPATH}"

# We have a packages directory, add to BBFILES
BBFILES := "${BBFILES} ${LAYERDIR}/recipes-*/*/*.bb \
${LAYERDIR}/recipes-*/*/*/*.bb \
${LAYERDIR}/recipes-*/*/*.bbappend"

Building Other Applications with wolfSSL

Support for building many open source projects with wolfSSL is included in the various recipes-* directories. As an example, take a look at recipes_support/curl/wolfssl_%.bbappend. This .bbappend adds --enable-curl to the wolfSSL configuration line via EXTRA_OECONF. curl_%.bbappend sets up curl to use wolfSSL as its crypto and TLS provider. curl_7.82.0.bbappend is a .bbappend specifically for adding wolfSSL support to curl version 7.82.0.

In the curl project, wolfSSL is supported upstream, but other projects may not have native wolfSSL support. We've added wolfSSL support to many popular open source projects, and the patches can be found in our open source projects (OSP) repository. Several of these patches are used here. OpenSSH is one example. Under recipes-connectivity/openssh/files, you'll find a patch for OpenSSH 8.5p1 that adds wolfSSL support. One directory up in recipes-connectivity/openssh, you'll find openssh_8.5p1.bbappend which

  1. Adds the patch to the build.
  2. Removes OpenSSH's OpenSSL dependency.
  3. Adds the wolfSSL dependency.
  4. Adds --with-wolfssl to the configuration line.

Additionally, there's another wolfssl_%.bbappend which adds --enable-openssh to the wolfSSL configuration. This is the general pattern you'll see for other projects that depend on wolfSSL, too.

This layer offers wolfSSL support for the following open source projects:

wolfSSL Example Application Recipes

The “meta-wolfssl” layer includes several example application recipes, for testing and example purposes. The current example recipes include:

  • wolfCrypt test application (depends on wolfssl)
  • wolfCrypt benchmark application (depends on wolfssl)

The recipe files for these applications are located at:

meta-wolfssl/recipes-examples/wolfcrypt/wolfcrypttest/wolfcrypttest.bb
meta-wolfssl/recipes-examples/wolfcrypt/wolfcryptbenchmark/wolfcryptbenchmark.bb

These can be compiled individually with bitbake:

$ bitbake wolfcrypttest
$ bitbake wolfcryptbenchmark

To install these applications into an image, edit the project’s “build/conf/local.conf” file and add them to the “IMAGE_INSTALL_append” variable. For example:

IMAGE_INSTALL_append = “wolfssl wolfcrypttest wolfcryptbenchmark”

When the image is built, these examples will then be installed by default to the “/usr/bin” directory.

Excluding Recipes from the Build

Not all users will want to compile all wolfSSL product, example, and support recipes included in the “meta-wolfssl” layer. Recipes can be excluded from the build by simply deleting their respective directories from the “meta-wolfssl” layer.

For example, to delete the wolfTPM recipe:

$ rm meta-wolfssl/recipes-wolfssl/wolftpm

Or, to delete the example applications:

$ rm meta-wolfssl/recipes-examples

Support and Maintenance

Please email the wolfSSL support team (support@wolfssl.com) with any questions or maintenance requests to the “meta-wolfssl” layer.

Consulting

wolfSSL has a wealth of experience in IoT and network appliance security which can be shared through professional consulting services. Under consulting services, wolfSSL can add additional Open Source project support with wolfSSL to the meta-wolfssl layer.

Please contact facts@wolfssl.com for more info.

License

wolfSSL, wolfMQTT, and wolfTPM are open source and dual licensed under both the GPLv2 and a standard commercial license. wolfSSH is open source and dual licensed under both the GPLv3 and a standard commercial license.

For commercial license questions, please contact wolfSSL at licensing@wolfssl.com.