Please note as of Wednesday, August 15th, 2018 this wiki has been set to read only. If you are a TI Employee and require Edit ability please contact x0211426 from the company directory.

Using wolfSSL with TI-RTOS

From Texas Instruments Wiki
Jump to: navigation, search


The wolfSSL Embedded SSL Library is a lightweight Secure Sockets Layer (SSL)/Transport Layer Security (TLS) library written in ANSI C and targeted for embedded, RTOS, and resource constrained environments primarily because of its small size, speed, and feature set.

TI-RTOS for TivaC product integrates wolfSSL with TI-RTOS NDK stack and provides secure TCP and HTTP examples that show how a TI-RTOS application can use the wolfSSL stack.


Supported targets and products

Targets

Products

    • TI-RTOS v2.14.04.31 or later
    • wolfSSL v3.6.8 - v3.11.0


Download

Download TI-RTOS and wolfSSL as follows:

TI-RTOS

Download the TI-RTOS for TivaC product from either of these locations:

WolfSSL

Download the wolfSSL product from:


Installation

Install TI-RTOS and wolfSSL as follows:

TI-RTOS

  • Run the installer and follow the instructions. We recommend installing TI-RTOS in the default location (i.e. C:/ti).

WolfSSL

  • If you downloaded an installer, run the installer and follow the instructions.
  • If you downloaded a *.zip file, extract the contents to your disk (for example, in C:/ti/wolfssl).


Build Instructions

For WolfSSL v3.8.0 or later

Setup

  1. Open a terminal or command prompt and type:
    cd wolfSSL_install_dir/tirtos
  2. Edit the products.mak file. Update the XDC_INSTALL_DIR, BIOS_INSTALL_DIR, NDK_INSTALL_DIR and TIVAWARE_INSTALL_DIR variables. XDCtools, BIOS, NDK, Tivaware products are part of the TI-RTOS installation. Update the code generation tools path for any of the tool chains - ti.targets.arm.elf.M4F (i.e. TI), iar.targets.arm.M4F (i.e. IAR) or gnu.targets.arm.M4F (i.e. GCC). After modification, these variable definitions should look similar to the following if you are working on Windows. (Windows users: note the use of "/" in the path).
    XDC_INSTALL_DIR = C:/ti/xdctools_3_31_01_33
    BIOS_INSTALL_DIR = C:/ti/tirtos_tivac_2_16_00_00/products/bios_6_45_01_23
    NDK_INSTALL_DIR = C:/ti/tirtos_tivac_2_16_00_00/products/ndk_2_25_00_08
    TIVAWARE_INSTALL_DIR = C:/ti/tirtos_tivac_2_16_00_00/products/TivaWare_C_Series-2.1.1.71b
    ti.targets.arm.elf.M4F = C:/ti/ccsv6/tools/compiler/ti-cgt-arm_5.2.4


NoteNote: Please set XDCTOOLS_JAVA_HOME variable if you are using XDCtools from the CCS installation. The variable has to be set to the JRE path (which is available in CCS).
For example: export XDCTOOLS_JAVA_HOME = C:/ti/ccsv6/eclipse/jre

Build

WolfSSL library for TI-RTOS has been configured to include the ciphers that are enabled by default. Users can update the configuration to include/exclude ciphers from the library. The TI-RTOS configuration in wolfSSL can be found wolfssl_install_dir/wolfssl/wolfcrypt/settings.h under #ifdef WOLFSSL_TIRTOS. Read building wolfSSL manual for the various build defines.

After configuration update (if any), build the wolfSSL libraries as follows:

  1. To build:
    make -f wolfssl.mak all
  2. To clean:
    make -f wolfssl.mak clean

If the "make" tool is not installed on your machine, you can use the "gmake" tool available in XDCtools which is installed along with TI-RTOS.

For older wolfSSL products

Setup

In order to build wolfSSL, you first need to update the wolfSSL installation directory path in TI-RTOS. Follow these steps:

  1. Open the tirtos.mak file in the TI-RTOS installation directory.
  2. In tirtos.mak, update the definition of WOLFSSL_INSTALL_DIR (or WOLFSSL_INSTALLATION_DIR) to point to the installed wolfSSL product path.
  3. (Optional) Update other build options, such as the code generation tools path and build targets. Information about these options can be found in the TI-RTOS User's Guide (SPRUHD4).

Build

WolfSSL library for TI-RTOS has been configured to include the ciphers that are enabled by default. Users can update the configuration to include/exclude ciphers from the library. The TI-RTOS configuration in wolfSSL can be found wolfssl_install_dir/wolfssl/wolfcrypt/settings.h under #ifdef WOLFSSL_TIRTOS. Read building wolfSSL manual for the various build defines.

NoteNote: For WolfSSL versions 3.6.6 and later, define HAVE_ECC in wolfssl_install_dir/wolfssl/wolfcrypt/settings.h under #ifdef WOLFSSL_TIRTOS. This workaround is required to run the TI-RTOS HTTPS example.

After configuration update (if any), build the wolfSSL libraries as follows:

  1. Open your choice of terminal or command prompt.
  2. Type the following command:
    cd tirtos_install_dir
  3. To build:
    make -f tirtos.mak wolfssl
  4. To clean:
    make -f tirtos.mak clean-wolfssl

If the "make" tool is not installed on your machine, you can use the "gmake" tool available in XDCtools which is installed along with TI-RTOS.


Linking with the wolfSSL library in your TI-RTOS application

Examples are provided as a part of the TI-RTOS product. See TI-RTOS for TivaC Getting Started Guide (SPRUHU5) for detailed information on importing projects into CCS or IAR and a list of examples that use WolfSSL.

The wolfSSL library path must be added to both the compiler and linker build options.

This process differs based on the compiler toolchain that you are building for (TI, IAR, and GNU). The library file path wolfSSL_lib will either be:

For software based cipher:

wolfSSL_install_dir/tirtos/packages/ti/net/wolfssl/lib/wolfssl.atarget

For hardware accelerated cipher (works only on Crypto Connected Launchpad):

wolfSSL_install_dir/tirtos/packages/ti/net/wolfssl/lib/wolfssl_tm4c_hw.atarget

Example building with the TI compiler:

For the EK-TM4C129EXL that supports hardware acceleration, the library could be)

C:/ti/wolfssl/tirtos/packages/ti/net/wolfssl/lib/wolfssl_tm4c_hw.aem4f

TI Compiler builds within CCS

1. Add the wolfSSL_install_dir path to Add dir to.. window within Build->ARM Compiler->Include Options.

TI CCS 1.png

2. Add the wolfSSL_lib to the Include Library File window within Build->ARM Linker->File Search Path.


TI CCS 2.png

GNU Compiler builds within CCS

1. Add the wolfSSL_install_dir path to the Include paths window within Build->GNU Compiler->Directories.

GNU CCS 1.png

2. Add :wolfssl.atarget (ie. :wolfssl.am4fg to the Libraries window within Build->GNU Linker->Libraries.

3. Add the wolfSSL_install_dir/tirtos/packages/ti/net/wolfssl/lib to the library search path window within Build->GNU Linker->Libraries.

GNU CCS 2.png


For extra help in adding the library file path to CCS please visit the following CCS help page.

IAR Compiler builds within IAR Embedded Workbench

1. Add the wolfSSL_install_dir path to the Additional include directories window within C/C++ Compiler->Preprocesor.

IAR 1.png

2. Add the wolfSSL_lib path to the Additional libraries window within Linker->library.

IAR 2.png

For Command line builds

The wolfssl library path must be added to the makedefs file to ensure the library ordering is correct to avoid linker errors.

Within the generated TIRTOS examples directory, located within your TIRTOS install directory, edit the
”TIRTOS_examples_dir”/”COMPILER”/”BOARD_dir”/makedefs file and add the correct WolfSSL library(See above) to the LFLAGS variable.

For reference, example link lines are shown for each toolchain below

For TI Command line builds

Ex 1) LFLAGS = -l"<WOLFSSL_lib>" <LINKERFLAGS> -llibc.a

Ex 2)

LFLAGS = -l"<WOLFSSL_lib>" -l$(TIVAWARE_INSTALL_DIR)/grlib/ccs/Debug/grlib.lib -l$(TIVAWARE_INSTALL_DIR)/driverlib/ccs/Debug/driverlib.lib EK_TM4C1294XL.cmd -m$(NAME).map --warn_sections --rom_model -i$(CODEGEN_INSTALL_DIR)/lib -llibc.a

For GNU Command line builds

The “WOLFSSL_lib" must appear after the specified linker flags but before all math libraries.

Ex 1) LFLAGS = <LINKERFLAGS> --gc-sections wolfSSL_lib “MATH_lib”

Ex 2)

"c:/ti/ccsv6/tools/compiler/gcc-arm-none-eabi-4_8-2014q3/bin/arm-none-eabi-gcc" EK_TM4C1294XL.obj httpsget.obj -Wl,-T,EK_TM4C1294XL.lds -Wl,-Map ,httpsget.map -Wl,-T,httpsget/linker.cmd -ldriver -march=armv7e-m -mthumb -mfloat-abi=hard -mfpu=fpv4-sp-d16 -nostartfiles -static -Wl,--gc-sections wolfSSL_lib -lgcc -lc -lm -lrdimon -o .out

For IAR Command line builds

Ex 1) LFLAGS = wolfSSL_lib “LINKERFLAGS”

Ex 2)

LFLAGS = wolfSSL_lib $(TIVAWARE_INSTALL_DIR)/driverlib/ewarm/Exe/driverlib.a --config EK_TM4C1294XL.icf --map $(NAME).map --silent --cpu=Cortex-M4F --entry=__iar_program_start

NoteNote: The crypto hardware accelerator library may need extra heap. Increase BIOS.heapSize in the .cfg file.



wolfSSL's TI-RTOS examples

Examples from the wolfSSL team can be downloaded from wolfSSL's examples GitHub.


Benchmarks

For more wolfSSL benchmark information, see wolfSSL's benchmarks.


CyaSSL support

Read Using CyaSSL with TI-RTOS wiki for using older versions of wolfSSL (formerly CyaSSL) with TI-RTOS.


References

User guides and manuals

Support