PulseRain Rattlesnake

RISC-V RV32IMC Soft CPU, with a Security-Hardened Processor Core

Overview
Quick Start
Folder Structure of the Repository
Simulation with Verilator
Regenerate the Bitstream
Zephyr
Security Strategy Details

1. Overview

PulseRain Rattlesnake is a RISC-V soft CPU with a Security-Hardened processor core. It supports RV32IMC instruction set, and carries a Von Neumann architecture.

As shown above, on top of a regular RV32IMC core (2 x 2 pipeline stage), 2 additional security units are added. They are:

ERPU (Execution Region Protection Unit)
DATU (Dirty Address Trace Unit)

These security units form two different security strategies:

Execution Region Protection (ERP)
Dirty Address Trace (DAT), with extended memory/register width to store dirty address bit.

To verify the effectiveness of the above two strategies, 5 mock tests from ripe program (https://github.com/Thales-RISC-V/RISC-V-IoT-Contest) are used as a bench mark. The 5 mock tests are compiled without any change to the compiler. And the results are shown as following:

	NR1	NR2	NR3	NR4	NR5
ERP	*Pass*	*Pass*	Fail	Fail	*Pass*
DAT	*Pass*	*Pass*	*Pass*	*Pass*	*Pass*

As indicated by the above table, the ERP strategy (which is similar to Physical Memory Protection in other processors) can only thwart 3 out of the 5 attacks, while the DAT strategy can thwart all of them. The details of the DAT strategy will be discussed at the end of this document.

In addition, the PulseRain Rattlesnake has been successfully ported to Future Electronics Creative board (IGLOO2), with a clock rate of 120MHz (for STD speed grade device), and a total power of 200mW.

And the Resource Usage on IGLOO2 (M2GL025) is as following (with 48KB memory size):

Resource Name	Resource Usage
Fabric 4LUT	4689
Fabric DFF	3129
Interface 4LUT	1224
Interface DFF	1224
uSRAM 1K	2
LSRAM 18K	28
Math 18x18	4

2. Quick Start

Clone the GitHub Repository

Assume Windows Platform is used. And assume Cygwin is installed. To clone the GitHub Repository of PulseRain Rattlesnake, do the following in Cygwin:

git clone https://github.com/PulseRain/Rattlesnake.git
cd Rattlesnake
git submodule update --init --recursive --progress

And the following is a screen capture for Cygwin operations on Windows 10

Program the Creative Board

On Windows 10, Download and Install Programming and Debug v12.1 for Windows.

Connect the Creative Board to the host PC through USB cable

Launch FPExpress v12.1, and open Rattlesnake\bitstream_and_binary\creative\Rattlesnake_flashpro_express\Rattlesnake_flashpro_express.pro

Click RUN to program the Creative Board, as shown below:

After the board is programmed, please unplug and re-plug the USB cable to make sure the board is properly re-initialized.

Running Software on the soft CPU

As illustrated below, a python script called rattlesnake_config.py is provided to load software (.elf file) into the soft CPU and execute. At this point, this script has only been tested on Windows platform.

Before using this script, the following should be done to setup the environment on Windows:

Install a RISC-V tool chain on Windows

It is recommended to use the RISC-V Embedded GCC. And its v8.2.0-2.2 release can be downloaded from here
After installation, add the RISC-V toolchain to system's $PATH

If default installation path is used, most likely the following paths need to be added to system's $PATH:

C:\GNU MCU Eclipse\RISC-V Embedded GCC\8.2.0-2.2-20190521-0004\bin
Install python3 on Windows

The latest python for Windows can be downloaded from https://www.python.org/downloads/windows/
After installation, add python binary and pip3 binary into system's $PATH

For example, if python 3.7.x is installed by user XYZ on Windows 10 in the default path, the following two folders might be added to $PATH:
```
C:\Users\XYZ\AppData\Local\Programs\Python\Python37

C:\Users\XYZ\AppData\Local\Programs\Python\Python37\Scripts
```
Open a command prompt (You might need to Run as Administrator), and install the pyserial package for python:

pip3 install pyserial
Make sure the Creative Board is connected to the host PC, and is programmed with the Rattlesnake bitstream.
Open the Device Manager in Windows to figure out which COM port is assigned to the Creative Board.
Enter the Rattlesnake\scripts directory. Assume COM7 is used by the hardware, then the following command can be used to load the ATTACK_NR1

python rattlesnake_config.py --port=COM7 --console_enable --reset --run --image=..\RISC-V-IoT-Contest\ATTACK_NR1\build\zephyr\zephyr.elf

And ATTACK_NR1's output is as following:

The other 4 attacks' output are as following:

ATTACK_NR2: python rattlesnake_config.py --port=COM7 --console_enable --reset --run --image=..\RISC-V-IoT-Contest\ATTACK_NR2\build\zephyr\zephyr.elf

ATTACK_NR3: python rattlesnake_config.py --port=COM7 --console_enable --reset --run --image=..\RISC-V-IoT-Contest\ATTACK_NR3\build\zephyr\zephyr.elf

ATTACK_NR4: python rattlesnake_config.py --port=COM7 --console_enable --reset --run --image=..\RISC-V-IoT-Contest\ATTACK_NR4\build\zephyr\zephyr.elf

ATTACK_NR5: python rattlesnake_config.py --port=COM7 --console_enable --reset --run --image=..\RISC-V-IoT-Contest\ATTACK_NR5\build\zephyr\zephyr.elf

The details of the 5 attacks will be discussed at the end of this document.

3. Folder Structure of the Repository

The folder structure of the GitHub Repository is illustrated below:

4. Simulation with Verilator

The PulseRain Rattlesnake can be simulated with Verialtor. To prepare the simulation and run the compliance test, the following steps (tested on Ubuntu and Debian hosts) can be followed:

Install zephyr-sdk 0.10.3
Install Verilator from https://www.veripool.org/wiki/verilator (or use apt-get install verilator). At this point, only Verilator version 4.0 or later is supported
git clone https://github.com/PulseRain/Rattlesnake.git
cd Rattlesnake
git submodule update --init --recursive --progress
cd sim/verilator
Build the verilog code and C++ test bench: make
Run the simulation for compliance test: make test_all

If everything goes smooth, the final output of the compliance test may look like the following:

As mentioned early, the PulseRain Rattlesnake soft CPU uses a hardware loader to load code/data. And for the verilator simulation, a C++ testbench will replace the hardware loader. The testbench will invoke the toolchain (objdump, readelf) to extract code/data from sections of the .elf file. The testbench will mimic the OCD bus to load the code/data into CPU's memory. Afterwards, the start-address of the .elf file ("_start" or "__start" symbol) will be passed onto the CPU, and turn the CPU into active state.

For the RV32IMC compliance test, there are total of 88 test cases. Among them, 55 are for RV32I, 25 are for C extension and 8 are for M extension. For each test case, the test bench will automatically extract the address for begin_signature and end_signature symbol. The compliance test will hold and load the soft CPU, and do the following:

Reset the CPU, put it into hold state
Call upon toolchain to extract code/data from the .elf file for the test case
Start the CPU, run for 2000 clock cycles
Reset the CPU, put it into hold state for the second time
Read the data out of the memory, and compare them against the reference signature

And the diagram below also illustrates the same idea:

And for the sake of completeness, the Makefile for Verilator supports the following targets:

make build : the default target to build the verilog uut and C++ testbench for Verilator
make test_all : run compliance test for all 88 cases
make test compliance_case_name : run compliance test for individual case. For example: make test I-ADD-01
make run elf_file : run sim on an .elf file for 2000 cycles.

5. Regenerate the Bitstream (SYN and PAR)

To build bitstream for Future Electronics Creative board (IGLOO2), do the following:

Install Microsemi Libero SoC V12.1 for Windows, and get a License for it if necessary.
Use Synplify Pro (Synplify Pro N-2018.03M-SP1-1, part of Microsemi Libero SoC V12.1) to open Rattlesnake\build\synth\Microchip\Rattlesnake.prj, and generate Rattlesnake.vm (It will be under Rattlesnake\build\synth\Microchip\IGLOO2)
Use a text editor (such as Notepad++) to open the Rattlesnake.vm generated above, search for those lines that contain the text "RAMINDEX", and comment those lines out by putting a "//" at the beginning of the line. This step is just a way to circumvent a bug of the Synplify Pro N-2018.03M-SP1-1.
Close Synplify Pro and use Libero SoC V12.1 to open Rattlesnake\build\par\Microchip\creative\creative.prjx
Generate bitstream with Libero SoC V12.1, and verify the timing is passed.

6. Zephyr

zephyr 1.14.1-rc1 (https://github.com/PulseRain/zephyr) has been successfully ported to PulseRain Rattlesnake. Basically, a board called rattlesnake is created, and a SoC called pulserain-rattlesnake is added. The details of the porting job can be found here. The OS infrastructure of zephyr has not been modified during the porting. Only a driver for UART and modifications to the Makefile were added.

To build applications for zephyr, please do the following under Linux:

Follow the instructions here to setup development environment.

The rest of the document assumes Linux is used as host for build, and Zephyr SDK 0.10.3 is used for toolchain.
To build for sample applications, users can do the following: (take the sample application of philosophers for example)

$ git clone https://github.com/PulseRain/zephyr.git
$ cd zephyr;rm -rf build
$ cmake -B build -DBOARD=rattlesnake -DCMAKE_VERBOSE_MAKEFILE:BOOL=ON VERBOSE=1 samples/philosophers
$ make -C build

And the elf file can be found in build/zephyr/zephyr.elf

In particular, to build the mock test from RISC-V-IoT-Contest, users can do the following: (take the ATTACK_NR1 for example)

$ git clone https://github.com/PulseRain/Rattlesnake.git
$ cd Rattlesnake
$ git submodule update --init --recursive --progress
$ cd RISC-V-IoT-Contest/ATTACK_NR1;rm -rf build
$ cmake -B build -DBOARD=rattlesnake -DCMAKE_VERBOSE_MAKEFILE:BOOL=ON VERBOSE=1 .
$ make -C build

And the elf file can be found in build/zephyr/zephyr.elf

7. Security Strategy Details

As mentioned early, PulseRain Rattlesnake mainly carries two security strategies: ERP and DAT. The details of those two strategies are now discussed below:

ERP (Executable Region Protection)

This strategy is similar to PMP (Physical Memory Protection) in other processors. Inside the Rattlesnake soft CPU, there is a module called ERPU (Executable Region Protection), which exposes two memory mapped registers:

0x2000002C	*Register for ERP Start Address*
0x20000030	*Register for ERP End Address*

Those two registers can only be written for once after reset. And usually those two registers are configured by bootloader. If the image is loaded from host PC, the loader script (In this case, rattlesnake_config.py) will configure them.

During normal operation, if PC is moved out of the region marked by ERP Start Address and ERP End Address, an exception (illegal instruction) will be thrown to stop the execution of malicious code.

The plus side of ERP strategy is:

easy to implement
hardware overhead is low

The drawbacks of ERP are:

Intrusive to software design. The bootloader or the application itself has to figure out the protected region, and do the proper configuration right after reset.
It can not defend against those attacks that invoke system code.

In fact, among the 5 mock tests (attacks), only 3 out of the 5 attacks can be thwarted by ERP. In order to thwart all 5 attacks, a more sophisticated defense scheme is needed. And for PulseRain Rattlesnake, the answer is DAT (Dirty Address Trace).

DAT (Dirty Address Trace)

Through the analysis of existing attack schemes, it is noticed that:

The attacker will usually take advantage of a software loophole to carry out buffer-overflow attacks
The buffer-overflow attack will overwrite certain pointers. For example, some direct attack scheme will overwrite the return address on the stack, and re-point it to malicious code.
To circumvent Physical Memory Protection, a more sophisticated scheme will set the pointer to code section, and invoke system functions such as a system console shell.
To circumvent other software guarding measures, such as stack canaries, some more sophisticated schemes will carry out indirect pointer attack, by modifying the pointer of a pointer.

Based on such observation, the DAT strategy is conceived to comprise the following 3 parts:

Expanded Memory and Register
Block Write Detection
Indirect Pointer Detection

1. DAT - Expand the memory and register width, add a dirty address bit

For PulseRain Rattlesnake, the memory is made of 4 banks, each bank is expanded from 8 bits to 9 bits, with 1 extra bit to indicate dirty address. The direct address bit is an indication for its content to be suspicious, as its content has been modified through block write. Fortunately, for most mainstream FPGA vendors, port width of 9 is natively supported by their block RAMs.

The 32 general purpose registers are also expanded by 1 bit. When data are loaded from memory to registers, the dirty address bit attached to the most significant byte will also be loaded into the highest bit (bit 32) of the expanded register.

2. DAT - Block Write Detection

The Block Write Detection will issue a dirty address flag if it seems a batch of consecutive write that are more than 8. Here the threshold 8 is used because according to the RISC-V calling convection, register s0-s7 need to be stored on the stack. A threshold of 8 will avoid the store of s0-s7 being flagged as dirty address.

The block write detection module will also take interrupt into account. Thus for a buffer-overflow to fly under the radar, its size has to be no more than 8, or it can manage to switch thread context every 8 write operations. For IoT application, this will make the attacker a lot more difficult to escape from the block write detection.

3. DAT - Indirect Pointer Detection

However, a more sophisticated attacker will use indirect pointer to circumvent the block write detection. To thwart such attackers, another module called indirect pointer detection is adopted by PulseRain Rattlesnake. The indirect pointer detection module will identify such indirect pointer, and spread the direct address bit to its final target address.

By observing the assembly code produced by the compiler (At this point, the GCC (ver 8.3) from zephyr-sdk 0.10.3 is used.), it can be concluded that the indirect pointer operation is done with the following instruction patterns:

1 LW   registerA, xxx(s0)
  Load something on the stack frame (s0 is the frame pointer) into registerA. 
  If the pointer is a global variable stored in data section, it may produce a different code pattern.

2. LW   registerB, xxx(registerA)
  indirect pointer(pointer of the pointer)
  
3. LW registerC, xxx(s0)
  If the pointer is a global variable stored in data section, it may produce a different code pattern.

4. SW registerC, (registerB)

The indirect pointer detection module will recognize the above pattern. For the last step, if registerC or registerB contains dirty address bit, such dirty address bit will be further spread into the memory word pointed by registerB.

For a memory word, merely having its dirty address bit set will not cause any reaction from the processor. However, if later on the processor sees a JAL instruction whose target address is dirty, the processor will throw an illegal instruction exception to prevent the malicious code from being reached.

4. DAT - Side Effect Discussion

Theoretically, the DAT would have some side effect for the software. If the software uses block copy to write a function table that is more than 8 items, the function table might be marked as dirty by DAT. However, practically it is very rare of normal code flow to do something like that, as most function table will be saved as constant, or modified individually instead of a batch fashion.

As a way to test this, the following two zephyr applications (philosopher and synchronization) have been tested along with DAT:

bitstream_and_binary\zephyr\philosophers_rv32imc.elf
bitstream_and_binary\zephyr\synchronization_rv32imc.elf

Users can use the following command (assume COM7 is used by the Create Board) to load them

python rattlesnake_config.py --port=COM7 --console_enable --reset --run --image=..\bitstream_and_binary\zephyr\philosophers_rv32imc.elf

python rattlesnake_config.py --port=COM7 --console_enable --reset --run --image=..\bitstream_and_binary\zephyr\synchronization_rv32imc.elf

TEST with RIPE

As mentioned early, for the 5 mock tests from ripe program (https://github.com/Thales-RISC-V/RISC-V-IoT-Contest), they can all be stopped by DAT alone. Here is a quick review of those 5 attacks: