Skip to content

MultiZone® Trusted Firmware is the quick and safe way to build secure IoT applications with any RISC-V processor. It provides secure access to commercial and private IoT clouds, real-time monitoring, secure boot, and remote firmware updates. The built-in Trusted Execution Environment provides hardware-enforced separation ...

License

Notifications You must be signed in to change notification settings

hex-five/multizone-iot-sdk

Repository files navigation

multizone-iot-sdk

MultiZone® Trusted Firmware is the quick and safe way to build secure IoT applications with any RISC-V processor. It provides secure access to commercial and private IoT clouds, real-time monitoring, secure boot, and remote firmware updates. The built-in Trusted Execution Environment provides hardware-enforced separation to shield the execution of trusted applications from untrusted 3rd party libraries.

Complete IoT firmware optimized for RISC-V processors:

  • Provides secure access to any IoT clouds, secure boot, remote firmware updates, etc.
  • Works with any RISC-V processor: no need for proprietary TrustZone-like hardware
  • Rapid development: pre-integrated TEE, TCP/IP, TLS/ECC, MQTT, FreeRTOS, GCC, Eclipse
  • Built-in Trusted Execution Environment RTOS providing 4 separated HW/SW “worlds”
  • Commercial open source license: no GPL contamination, no royalties, priced per design

MultiZone® Trusted Firmware works with any 32-bit and 64-bit RISC-V processor with standard U-mode extension. For a quick start, we recommend the development kit based on the open source softcore X300 developed by Hex Five Security. It is an enhanced version of the E300 SoC (Rocket rv32) originally developed at U.C. Berkeley. Like the E300, the X300 is designed to be programmed onto a Xilinx Artix-7. The X300 bitstream is entirely free for commercial and non-commercial use.

This version of MultiZone® Trusted Firmware supports the following hardware development kits:

This repository is for the Digilent ARTY board.

The Arty FPGA Evaluation Kit requires the following open source softcore:

For instructions on how to upload the bitstream to the ARTY board and how to connect the Olimex debug head ARM-USB-TINY-H see Arty FPGA Dev Kit Getting Started Guide and connecting the FPGA to a JTAG debugger

Quick Start

Prebuilt fpga bitstreams including the X300 RISC-V SoC and the MultiZone Trusted Firmware are provided as release assets ready to go:

If you are impatient to run the MultiZone Trusted Firmware demo, just upload the right bitstream to your Arty board and skip all steps below. For this you only need Xilinx Vivado Lab an the instructions at https://github.com/hex-five/multizone-fpga#readme

Installation

The MultiZone SDK works with any versions of Linux, Windows, and Mac capable of running Java 1.8 or greater. The directions in this readme have been carefully verified with fresh installations of Ubuntu 20.04, Ubuntu 19.10, Ubuntu 18.04.5, and Debian 10.5. Other Linux distros are similar. Windows developers may want to install a Linux emulation environment like MYSYS2/MinGW64 or, even better, Windows Subsystem for Linux. Hex Five's precompiled gnu toolchain and openOCD for Windows are available at https://hex-five.com/download/

Linux prerequisites

sudo apt update
sudo apt install git make default-jre libhidapi-dev libftdi1-2
sudo apt install gtkterm mosquitto-clients

Note: the package gtkterm is optional and required only to connect to the reference application via a local terminal. It is not required to build, debug, and load the MultiZone firmware or to connect to the target via Ethernet. Any other serial terminal application of choice would do.

Note: the package mosquitto-clients is optional and required only to test MQTT funcionality including telemetry and remote firmware updates. It is not required to build, debug, and load the MultiZone firmware or to connect to the target via Ethernet. Any other MQTT client application of choice would do.

Ubuntu 18.04 LTS additional dependency

sudo add-apt-repository "deb http://archive.ubuntu.com/ubuntu/ focal main universe"
sudo apt update
sudo apt install libncurses-dev

GNU RISC-V Toolchain

Hex Five reference build: RISC-V GNU Toolchain Linux 64-bit June 18, 2021

cd ~
wget https://hex-five.com/wp-content/uploads/riscv-gnu-toolchain-20210618.tar.xz
tar -xvf riscv-gnu-toolchain-20210618.tar.xz

OpenOCD on-chip debugger

Hex Five reference build: RISC-V openocd Linux 64-bit August 7, 2021

cd ~
wget https://hex-five.com/wp-content/uploads/riscv-openocd-20210807.tar.gz
tar -xvf riscv-openocd-20210807.tar.gz

Linux USB udev rules

sudo vi /etc/udev/rules.d/99-openocd.rules

# Future Technology Devices International, Ltd FT2232C Dual USB-UART/FIFO IC
SUBSYSTEM=="tty", ATTRS{idVendor}=="0403",ATTRS{idProduct}=="6010", MODE="664", GROUP="plugdev"
SUBSYSTEM=="usb", ATTR{idVendor} =="0403",ATTR{idProduct} =="6010", MODE="664", GROUP="plugdev"

# Olimex Ltd. ARM-USB-TINY-H JTAG interface
SUBSYSTEM=="tty", ATTRS{idVendor}=="15ba",ATTRS{idProduct}=="002a", MODE="664", GROUP="plugdev"
SUBSYSTEM=="usb", ATTR{idVendor} =="15ba",ATTR{idProduct} =="002a", MODE="664", GROUP="plugdev"

Reboot for these changes to take effect.

MultiZone IoT SDK

cd ~
git clone --recursive https://github.com/hex-five/multizone-iot-sdk.git
cd multizone-iot-sdk
git apply -p1 ext/lwip.patch --directory=ext/lwip
git apply -p1 ext/freertos.patch --directory=ext/freertos

Important: make sure to apply the lwIP patch above. Without the lwIP patch the firmware is NOT secure!

Important: FreeRTOS is optional as the MultiZone TEE provides its own RTOS. If you intend to use FreeRTOS, make sure to apply the freertos patch above.

Build & load the MultiZone IoT firmware

Connect the target board to the development workstation as indicated in the user manual. 'ls multizone-iot-sdk/bsp' shows the list of supported targets: X300. Assign one of these values to the BOARD variable - default is X300.

cd ~/multizone-iot-sdk
export RISCV=~/riscv-gnu-toolchain-20210618
export OPENOCD=~/riscv-openocd-20210807
export BOARD=X300
make 
make load

Note: With some older versions of the ftdi libraries, the first "make load" after powering the board may take a bit longer. If you don't want to wait, the simple workaround is to reset the FPGA board to abort the openOCD session. If you do this, make sure to kill the openocd process on your computer. Subsequent loads will work as expected and take approximately 10 seconds.

Connect the device to the MQTT Broker

Make sure switch SW3 is positioned close to the edge of the board.

Make sure the board is properly powered. An external power adapter 7-15V connected to J13 is recomended. USB hubs and weak computer USB ports will interfere with Ethernet operations and result in unexpected random behavior.

Disconnect the JTAG connector if OpenOCD is not in use otherwise the CPU is permanently halted and the system won't boot.

Connect the UART port (ARTY micro USB J10) as indicated in the user manual. On your computer, start a serial terminal console (gtkterm) and connect to /dev/ttyUSB1 at 115200-8-N-1.

Connect the Ethernet port to an Internet router, or to your computer if Internet sharing is enabled - see https://help.ubuntu.com/community/Internet/ConnectionSharing. The router should provide DHCP configuration including one DNS servers. There is no need to open inbound ports for the MQTT client to work. If your local network blocks outbound connections to the default MQTT/TLS port 8883, you can reconfigure the client to use the HTTPS/TLS port 443, which is usually open - see MQTT configuration file mqtt_config.h

Press the reset button on the board and hit the enter key a few times on your serial terminal to synchronize the UART port.

After a few seconds the client should connect to the Hex Five's public MQTT broker:

=====================================================================
      	             Hex Five MultiZone® Security                    
    Copyright© 2020 Hex Five Security, Inc. - All Rights Reserved    
=====================================================================
This version of MultiZone® Security is meant for evaluation purposes 
only. As such, use of this software is governed by the Evaluation    
License. There may be other functional limitations as described in   
the evaluation SDK documentation. The commercial version of the      
software does not have these restrictions.                           
=====================================================================
Machine ISA   : 0x40101105 RV32 ACIMU 
Vendor        : 0x0000057c Hex Five, Inc. 
Architecture  : 0x00000001 X300 
Implementation: 0x20181004 
Hart id       : 0x0 
CPU clock     : 64 MHz 
RTC clock     : 16 KHz 

PLIC @0x0c000000
DMAC @0x10040000
UART @0x10013000
GPIO @0x10012000
EMAC @0x60000000

Z1 > netif_link_callback: up
 
Z1 > netif_status_callback: address 192.168.0.130
 
Z1 > dns_callback: mqtt-broker.hex-five.com 54.176.2.35
 
Z1 > sntp_process: 1634164010 Wed Oct 13 15:29:30 2021
 
Z1 > client_id: mzone-2094fc9a
 
Z1 > mqtt: connecting ... 
 
Z1 > mqtt: connected 
 
Z2 >

Hit enter on an empty line to show the list of commands available:

Z2 > Commands: yield send recv pmp load store exec dma stats timer restart
  • yield: yield the CPU to the next zone showing the time taken to loop through all zones
  • send/recv: exchange messages with any zones. Zone 1 is the gateway to the MQTT broker: messages sent to zone 1 are forwarded to the broker topic device-id/zone. Messages sent to the broker topic device-id/zone are forwarded to the respective zone
  • pmp: show the separation policies for zone 2, which is the zone operating the local terminal
  • load/store: read and write data from/to any arbitrary physical memory location
  • exec: jump the execution of the zone to any arbitrary memory location
  • dma: submit a protected DMA transfer request
  • stats: repeat the yield command multiple times and print detailed kernel statistics
  • timer: set the zone timer to current time plus a time delay expressed in milliseconds
  • restart: jump the execution of this zone to the base address of the first pmp range restarting the zone

For a detailed explanation of the features of the MultiZone TEE see the MultiZone TEE Reference Manual

Note: take note of your randomly generated client_id as you'll need it to interact with the target via MQTT messages published and subscribed to topics mzone-xxxxxxxx/zonex (mzone-2094fc9a in the example above). The MQTT client_id is generated randomly for each new MQTT session upon board reset.

Send and receive MQTT messages

cd ~/multizone-iot-sdk
export MQTT=" --host mqtt-broker.hex-five.com"
export MQTT=$MQTT" --cafile pki/hexfive-ca.crt"
export MQTT=$MQTT" --cert pki/test.crt"
export MQTT=$MQTT" --key pki/test.key"

Note: in the following examples replace "mzone-2094fc9a" with your randomly generated client id.

Subscribe (listen) to all topics for your device - background process:

mosquitto_sub $MQTT -t mzone-2094fc9a/# -v &

Publish (send) a "ping" message to zone #1:

mosquitto_pub $MQTT -t mzone-2094fc9a/zone1 -m ping

Observe the "pong" reply received in the background.

Deploy Remote Firmware Updates

Deploy the rainbow LED appication to zone #3 (binary zone3.1/zone3.bin):

mosquitto_pub $MQTT -t mzone-2094fc9a/zone3 -f zone3.1/zone3.bin

Delopy the robot application to zone #4 (binary zone4.1/zone4.bin):

mosquitto_pub $MQTT -t mzone-2094fc9a/zone4 -f zone4.1/zone4.bin

Optional: delopy the FreeRTOS-based version of the robot application (binary zone4.2/zone4.bin):

mosquitto_pub $MQTT -t mzone-2094fc9a/zone4 -f zone4.2/zone4.bin

Note: For a complete explanation of the functionality of each zone/application see the MultiZone SDK Reference Manual.

Technical Specs

Stack Component

Features

Size

License

Reference Hardware

Digilent ARTY7 35T/100T FPGA

Hex Five X300 SoC IP

 

RISC-V core RV32ACIMU 4-way i-cahe 65MHz

Ethernet: Xilinx EthernetLite Ethernet core

Apache 2.0 license

permissive

commercial use ok

IDE & Toolchain

Eclipse IDE + openOCD debug

GNU GCC, GDB, …

GCC multi-lib rv32, rv32e, rv64, GDB, openOCD

Hex Five pre-built GCC binaries (optional)

Hex Five pre-built OpenOCD binaries (optional)

GNU General Public License version 3

TCP/IP library

LWIP 2.1.3

Hex Five security extensions

IP, ICMP, UDP, TCP, ARP, DHCP, DNS, SNTP, MQTT

Light weight single threaded execution

Fully integrated with SSL stack

40KB ROM

16KB RAM

Modified BSD

permissive

commercial use ok

SSL library

mbed TLS 2.28.1

Hex Five secure configuration

TLSv1.2, Cipher TLS_AES_128_GCM_SHA256

ECC: prime256v1, Private Key NIST CURVE: P-256

Mutual authentication, Cert expiration verification, TLS large fragment

64KB ROM

32KB RAM

Apache 2.0 license

permissive

commercial use ok

Real Time OS (optional)

FreeRTOS 10.3.0

Hex Five integration with TEE

Secure unprivileged execution of kernel, tasks, and interrupt handlers

No memory shared with TCP/IP and SSL library code

No memory shared with other applications running in separate zones

32KB ROM

16KB RAM

MIT open-source license

permissive

commercial use ok

Trusted Execution Environment

MultiZone Security TEE 2.2.2

RISC-V secure DMA extension

RISC-V shared PLIC extension

4 separated Trusted Execution Environments (zones) enforced via PMP

8 memory-mapped resources per zone – i.e. ram, rom, i/o, uart, gpio, eth, …

Secure inter-zone messaging – no shared memory, no buffers, no stack, etc

Protected user-mode interrupt handlers mapped to zones – plic / clint

8KB ROM

2KB RAM

Free evaluation

Commercial license priced per design perpetual, no royalties, no GPL contamination

Additional Resources

Legalities

Please remember that export/import and/or use of strong cryptography software, providing cryptography hooks, or even just communicating technical details about cryptography software is illegal in some parts of the world. So when you import this software to your country, re-distribute it from there or even just email technical suggestions or even source patches to the authors or other people you are strongly advised to pay close attention to any laws or regulations which apply to you. Hex Five Security, Inc. and the authors of the software included in this repository are not liable for any violations you make here. So be careful, it is your responsibility.

MultiZone and HEX-Five are registered trademarks of Hex Five Security, Inc.

MultiZone technology is protected by patents US 11,151,262 and PCT/US2019/038774

About

MultiZone® Trusted Firmware is the quick and safe way to build secure IoT applications with any RISC-V processor. It provides secure access to commercial and private IoT clouds, real-time monitoring, secure boot, and remote firmware updates. The built-in Trusted Execution Environment provides hardware-enforced separation ...

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published