wolfSSL with Arduino

The published wolfssl library source for Arduino is found in Arduino-wolfSSL.

See the example sketches:

Bare-bones templates:

• sketches/wolfssl_version single file.
• sketches/template multiple file example.

Functional examples:

• sketches/wolfssl_AES_CTR AES CTR Encrypt / decrypt.
• sketches/wolfssl_client TLS Client.
• sketches/wolfssl_server TLS Server.
• sketches/wolfssl_client_dtls DTLS Client.
• sketches/wolfssl_server_dtls DTLS Server.

Both the template and wolfssl_AES_CTR examples include VisualGDB project files.

When publishing a new version to the Arduino Registry, be sure to edit WOLFSSL_VERSION_ARUINO_SUFFIX in the wolfssl-arduino.sh script.

Getting Started

See Getting Started with wolfSSL on Arduino, wolfSSL features are enabled and disabled in the user_settings.h file.

The user_settings.h file is found in the <Arduino>/libraries/wolfssl/src directory.

For Windows this is typically C:\Users\%USERNAME%\Documents\Arduino\libraries\wolfssl\src

For Mac: ~/Documents/Arduino/libraries/wolfssl/src

For Linux: ~/Arduino/libraries/wolfssl/src

Tips for success:

• The WOLFSSL_USER_SETTINGS macro must be defined project-wide. (see wolfssl.h)
• Apply any customizations only to user_settings.h; Do not edit wolfSSL settings.h or config.h files.
• Do not explicitly include user_settings.h in any source file.
• For every source file that uses wolfssl, include wolfssl/wolfcrypt/settings.h before any other wolfSSL include, typically via #include "wolfssl.h".
• See the wolfSSL docs for details on build configuration macros.

Boards

Many of the supported boards are natively built-in to the Arduino IDE Board Manager and by adding additional cores as needed.

STM32 Support can be added by including this link in the "Additional Boards Managers URLs" field from stm32duino/Arduino_Core_STM32.

https://github.com/stm32duino/BoardManagerFiles/raw/main/package_stmicroelectronics_index.json

or

https://raw.githubusercontent.com/stm32duino/BoardManagerFiles/main/package_stmicroelectronics_index.json

ESP8266 Support uses this:

http://arduino.esp8266.com/stable/package_esp8266com_index.json

STM32Duino:

http://dan.drown.org/stm32duino/package_STM32duino_index.json,

Teensy:

https://www.pjrc.com/teensy/package_teensy_index.json

There are Arduino-specific, compile-time (macros & includes) of interest for these files:

• settings.h
• settings.h

Using wolfSSL from the Arduino IDE

The Official wolfSSL: https://github.com/wolfSSL/arduino-wolfSSL See PR #1.

This option will allow wolfSSL to be installed directly using the native Arduino tools.

Manually Reformatting wolfSSL as a Compatible Arduino Library

Use this shell script that will re-organize the wolfSSL library to be compatible with Arduino Library Specification for projects that use Arduino IDE 1.5.0 or newer.

The Arduino IDE requires a library's source files to be in the library's root directory with a header file in the name of the library. This script moves all src/ files to the IDE/ARDUINO/wolfSSL/src directory and creates a stub header file called wolfssl.h inside that directory.

Step 1:

A local wolfssl core library proper is needed.

Examples below assume the wolfssl is cloned to wolfssl-$USER:

cd /mnt/c/workspace
git clone https://github.com/wolfSSL/wolfssl wolfssl-$USER

or for Windows:

cd c:\workspace
git clone https://github.com/wolfSSL/wolfssl wolfssl-%USERNAME%

To configure wolfSSL with Arduino, enter ONE of the following 4 commands from within the wolfssl/IDE/ARDUINO directory:

1. ./wolfssl-arduino.sh

   • Creates an Arduino Library directory structure in the local wolfSSL directory of IDE/ARDUINO.
   • You can add your own user_settings.h, or copy/rename the default.

2. ./wolfssl-arduino.sh INSTALL (The most common option)

   • Creates an Arduino Library in the local wolfSSL directory
   • Moves that directory to the Arduino library directory:
     • $HOME/Arduino/libraries for most bash environments
     • /mnt/c/Users/$USER/Documents/Arduino/libraries (for WSL)
   • Adds the default as user_settings.h.
   • The wolfSSL library is now available from the Arduino IDE.

3. ./wolfssl-arduino.sh INSTALL /path/to/repository (Used to update arduino-wolfSSL)

   • Creates an Arduino Library in wolfSSL directory
   • Copies that directory contents to the specified /path/to/repository
   • Adds the default as user_settings.h.

4. ./wolfssl-arduino.sh INSTALL /path/to/any/other/directory

   • Creates an Arduino Library in wolfSSL directory
   • Copies that directory contents to the specified /path/to/any/other/directory

Step 2:

Edit <arduino-libraries>/wolfSSL/src/user_settings.h If building for Intel Galileo platform add: #define INTEL_GALILEO. Add any other custom settings. For a good start see the examples in wolfssl root "/examples/configs/user_settings_*.h"

Step 3:

If you experience any issues with custom user_settings.h see the wolfssl porting guide here for more assistance: https://www.wolfssl.com/docs/porting-guide/

If you have any issues contact [email protected] for help.

Including wolfSSL in Arduino Libraries (for Arduino version 2.0 or greater)

1. In the Arduino IDE:

The wolfSSL library should automatically be detected when found in the libraries directory.

• In Sketch -> Include Library choose wolfSSL for new sketches.

wolfSSL Examples

Open an example Arduino sketch for wolfSSL:

• template: sketches/template/template.ino

• wolfssl_AES_CTR: sketches/wolfssl_AES_CTR/wolfssl_AES_CTR.ino

• wolfSSL Client INO sketch: sketches/wolfssl_client/wolfssl_client.ino

• wolfSSL Server INO sketch: sketches/wolfssl_server/wolfssl_server.ino

• wolfssl_version: sketches/wolfssl_version/wolfssl_version.ino

Script Examples

Refresh the local Windows Arduino wolfSSL library from GitHub repository directory using WSL:

Don't forget to edit WOLFSSL_VERSION_ARUINO_SUFFIX!

# Change to the wolfSSL Arduino IDE directory
cd /mnt/c/workspace/wolfssl-$USER/IDE/ARDUINO

# remove current Arduino wolfSSL library
rm -rf /mnt/c/Users/$USER/Documents/Arduino/libraries/wolfssl

# Install wolfSSL as an Arduino library
./wolfssl-arduino.sh INSTALL

Publish wolfSSL from WSL to a Arduino-wolfSSL-$USER repository.

cd /mnt/c/workspace/wolfssl-$USER/IDE/ARDUINO
rm -rf /mnt/c/Users/$USER/Documents/Arduino/libraries/wolfSSL
rm -rf /mnt/c/workspace/wolfssl-$USER/IDE/ARDUINO/wolfSSL
./wolfssl-arduino.sh INSTALL /mnt/c/workspace/Arduino-wolfSSL-$USER/

Publish wolfSSL from WSL to default Windows local library.

cd /mnt/c/workspace/wolfssl-$USER/IDE/ARDUINO
rm -rf /mnt/c/Users/$USER/Documents/Arduino/libraries/wolfSSL
rm -rf /mnt/c/workspace/wolfssl-arduino/IDE/ARDUINO/wolfSSL
./wolfssl-arduino.sh INSTALL

Test the TLS server by running a local command-line client.

cd /mnt/c/workspace/wolfssl-$USER
./examples/client/client -h 192.168.1.43 -p 11111 -v 3

Build wolfSSL to include wolfSSH support to an alternate development directory.

cd /mnt/c/workspace/wolfssl-$USER
./configure --prefix=/mnt/c/workspace/wolfssh-$USER/wolfssl_install --enable-ssh
make
make install

Build wolfSSH with wolfSSL not installed to default directory.

cd /mnt/c/workspace/wolfssh-$USER
./configure --with-wolfssl=/mnt/c/workspace/wolfssh-$USER/wolfssl_install
make
./examples/client/client -u jill -h 192.168.1.34 -p 22222 -P upthehill

Test the current wolfSSL.

cd /mnt/c/workspace/wolfssl-arduino
git status
./autogen.sh
./configure --enable-all
make clean
make && make test

Build and run testwolfcrypt.

./autogen.sh
./configure --enable-all
make clean && make && ./wolfcrypt/test/testwolfcrypt

Testing

See the enclose board_list.txt file: a list of fully qualified board names that is used by the github/workflows/arduino.yml action.