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.2, and can be easily combined with any of wolfSSL’s other products (SSH. One of the security measures we can take in our Yocto Image is to avoid root user login over SSH. The SSH server which gets installed on the image with core-image-sato is 'dropbear' To avoid root login over SSH.
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
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.2, 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.
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.
Yocto Ssh 2
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.
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:
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:
To install wolfSSL, wolfSSH, wolfMQTT, and wolfTPM:
To install wolfSSL and the wolfCrypt test and benchmark applications:
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.
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.
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:
Inside this .bbappend file, use the EXTRA_OECONF variable to add additional configure options to the wolfSSL library build. To enable SHA-512:
Or, another example might be enabling support for TLS 1.3:
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:
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:
These can be compiled individually with bitbake:
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:
When the image is built, these examples will then be installed by default to the “/usr/bin” directory.
Excluding Recipes from the Build
Yocto Sshd
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:
Or, to delete the example applications:
Support and Maintenance
Please email the wolfSSL support team (support@wolfssl.com) with any questions or maintenance requests to the “meta-wolfssl” layer.
Yocto Ssh Recipe
License
Yocto Sshfs
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.