Using CyaSSL with TI-RTOS

This page is currently under construction. The content of this page is due to change quite frequently and thus the quality and accuracy are not guaranteed until this message has been removed. Please feel free to contribute to this page while construction is in progress.

The CyaSSL 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 provides an example called "tcpEchoTLS" that shows how a TI-RTOS application can use the CyaSSL stack.

Supported targets and products

• Targets: ARM Cortex-M4F on the TM4C1294XL Launchpad
• Products:
  • TI-RTOS v2.10.01.38 or later
  • CyaSSL v3.2.0 - v3.3.0
  • (Optional) Socat v1.7.2.1 or later. (Open source tool for testing the tcpEchoTLS example.)

Download

Download TI-RTOS and CyaSSL as follows:

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

• TI-RTOS webpage
• The App Center in Code Composer Studio

CyaSSL: Download the CyaSSL product from one of these locations:

• TI eStore -- a TI licensed product
• WolfSSL download page -- a GPL licensed product
• Clone it from WolfSSL’s CyaSSL GitHub repository -- a GPL licensed product

(Optional) Socat:

• For Linux, the tool is generally part of standard Linux distribution (like Ubuntu, SuSE).
• For Windows, download it from the Socat website.

Installation

Install TI-RTOS and CyaSSL as follows:

TI-RTOS:

• Run the installer and follow the instructions.

CyaSSL:

• 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:/cyassl).
• If you are cloning it from WolfSSL’s CyaSSL GitHub repository, store it on your disk (for example, in C:/cyassl).

(Optional) Socat:

• On Linux, it is pre-installed.
• On Windows, extract the contents of the zip file to your disk (for example, to C:/SOCAT).

Setup

In order to build CyaSSL, you first need to update the CyaSSL 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 CYASSL_INSTALLATION_DIR to point to the installed CyaSSL 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).

NOTE: For GNU, before building CyaSSL libraries add "-D_POSIX_SOURCE" to cyasslPathInclude variable in '<CyaSSL root directory>/tirtos/cyassl.bld'.

Building CyaSSL libraries

After performing the set up steps, build the CyaSSL 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 cyassl
   
4. To clean:
   make -f tirtos.mak clean-cyassl
   

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.

Building TI-RTOS CyaSSL example applications

TI-RTOS provides an application called "tcpEchoTLS" that uses the CyaSSL stack. The source for this example and a readme file with further information is provided in tirtos_install_dir\packages\examples\source\tcpEchoTLS.

There are three ways to build this TI-RTOS CyaSSL example application. All these options are discussed in detail in the TI-RTOS for TivaC Getting Started Guide (SPRUHU5).

On the command line using makefiles:

If you want to build the example from the command line, you will need to generate the example first and then build it.

1. To generate the example, open your choice of terminal or command prompt, and type the following commands, where the destination_path_for_examples is the location where you want the example tree to be generated:
   cd tirtos_install_dir
make -f tirtos.mak examplesgen DEST="destination_path_for_examples"
2. To build the tcpEchoTLS example:
   cd destination_path_for_examples/tirtos_<version>_examples/TI/EK_TM4C1294XL/tcpEchoTLS
3. Read the "Build Details" section of the tcpEchoTLS_readme.txt file for example build steps.
4. Run the following command to build the example.
   make
5. Load and run the example on the target. The IP address of the application should be printed to the console attached.
6. Read the "Example Usage" section of the tcpEchoTLS_readme.txt file for steps to test the application, including how to connect to a client tool (either Socat or the CyaSSL echoclient).

In Code Composer Studio (CCS):

1. In CCS, choose View > Resource Explorer (Examples) from the menus.
2. Type "TCP Echo with TLS" in the "enter search keyword" field.
3. Select the TCP Echo with TLS example from the TI Target Examples. The full path to this example is TI-RTOS for TivaC > Tiva C Series > Tiva TM4C1294NCPDT > Driver Examples > EK-TM4C1294 > TI Target Examples > Ethernet Examples > TCP Echo with TLS.
4. In the right panel, click the Import the example project into CCS link.
5. Before building the example, read the "Build Details" section of the tcpEchoTLS_readme.txt file for example build steps.
6. In the TI Resource Explorer panel, click the Build the imported project, Debugger Configuration, and Debug the imported project links to build and debug the application.
7. In the CCS Debug perspective, run the application. The IP address of the application should be printed to the console.
8. Read the "Example Usage" section of the tcpEchoTLS_readme.txt file for steps to test the application, including how to connect to a client tool (either Socat or the CyaSSL echoclient).

In IAR Embedded Workbench:

1. In IAR, choose Project > Create New Project from the menus.
2. Select the Tool chain, and select the "Empty project" template. Click OK.
3. Browse to the location where you want to save this project, and type a file name for the project file (*.ewp). Click Save.
4. Choose Help > Information Center and click the Integrated Solutions icon.
5. Scroll down and click the icon for Texas Instruments example projects.
6. Click the link to the example applications.
7. Expand the example tree and select the EK-TM4C1294XL > Ethernet Examples > TCP Echo with TLS example.
8. Choose File > Save Workspace. Browse to the location where you want to save this workspace, and type a file name for the workspace file (*.eww). Click Save.
9. Before building the example, read the "Build Details" section of the tcpEchoTLS_readme.txt file for example build steps.
10. Build the project by choosing Project > Make.
11. Download and run the application. The IP address of the application should be printed to the Terminal I/O.
12. Read the "Example Usage" section of the tcpEchoTLS_readme.txt file for steps to test the application, including how to connect to a client tool (either Socat or the CyaSSL echoclient).

Benchmarks and CyaSSL API tests

Applications have been provided to benchmark the CyaSSL cryptography algorithms or test the CyaSSL APIs. These applications will be built along with the CyaSSL libraries. They can be found in cyassl_install_dir/tirtos/packages/ti/net/cyassl/tests/ctaocrypt.

Load and run the built executable on the target. The results are printed out on the console.

For more CyaSSL benchmark information, see WolfSSL's benchmarks.

WolfSSL's TI-RTOS CyaSSL examples

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

Useful references:

User guides and manuals:

• TI-RTOS for TivaC Getting Started Guide (SPRUHU5)
• TI-RTOS User's Guide (SPRUHD4)
• CyaSSL Manual

Support:

• TI-RTOS support forum
• CyaSSL support forum