CW305 Shell

This repository provides a shell template for NewAE CW305 FPGA. Vivado 2023.2 was used to verify the design.

Overview

CW305 is an FPGA board of ChipWhisperer family, which is designed for side-channel analysis. The board has a Xilinx Artix-7 FPGA and Atmel SAM3U microcontroller. The microcontroller is responsible for data communication between the host PC and the FPGA, including programming the FPGA. A dedicated bus between the FPGA and the microcontroller consists of 8 bits of data and 21 bits of address. However, there is no handshake primitive in the bus and thus, the FPGA must respond to the microcontroller within a fixed cycle. This shell template mitigates the issue by introducing ACK-based communication protocol. This feature allows the FPGA design variable latency data access. In addition, the shell template converts the read/write request from the host PC to AXI4-Lite protocol, which is widely used. Such a common bus interface enables you to easily evaluate your cryptographic module or soft macro IP on the FPGA.

Clock domain crossing

The shell template allows you to implement the cryptographic module with a different clock frequency from the microcontroller interface. Xilinx AXI Interconnect IP is used to convert the clock domain regarding AXI bus. The force trigger signal sent by the microcontroller is synchronized with the clock of the cryptographic module based on 2-phase handshake protocol by our interface module.

Create a project from the template

First, clone this repository.

git clone --recursive https://github.com/hal-lab-u-tokyo/cw305-shell.git
cd cw305-shell

The following command will launch Vivado and create a project

vivado -source vivado/init-shell-project.tcl

For more details, see doc/create_project.md.

ChipWhispere extension for communication with the shell

Our ChipWhisperer extension includes a driver to communicate with the shell based on ChipWhisperer API. First, install the extension according to the instruction in the repository.

The following is an example code to instantiate the shell object.

import chipwhisperer as cw
from cw_plugins.targets.CW305Shell import CW305Shell

# Connect to oscilloscope to capture power traces
scope = cw.scope()

# Connect to the CW305 board and configure the FPGA with the shell design
bsfile = "path/to/bitstream_file"
hwh_file = "path/to/hwh_file"
target = cw.target(scope, CW305Shell, bsfile=bsfile, hwh_file=hwh_file)

# Setup the target with default settings
target.setup()


# Example: LED control with high-level API
target.fpga_led_on(CW305Shell.LED_COLOR.BLUE)

# Example: Same way as the low-level API
led_addr = target.memmap.axi_gpio.base + 0x8
target.fpga_write(led_addr, 1)

CW305Shell.memmap provides the address map of the shell design, which is decoded from the HWH file. The HWH file is generated by the Vivado project in <vivado_proj>/<proj_name>.gen/sources_1/bd/main/hw_handoff/.

Block design examples to integrate cryptographic modules

This repository contains cryptographic module examples as a submodule. Detailed information about each example is available in the submodule repository.

examples directory includes scripts to create block designs with the cryptographic modules.

RTL implementations of AES 128-bit encryption

After creating a project with the template, as described above, you can create a block design by running the following command in the Vivado Tcl console.

source <path to this repo>/examples/aes128_aist_rtl/create_bd.tcl

To run the encryption with the design, please use CW305ShellExampleAES128BitRTL class in the ChipWhisperer Plugin.

Other RTL implementations of AES 128-bit encryption are available in examples/aes128_googlevault_rtl and examples/aes128_rsm_rtl. For aes128_rsm_rtl, you need to generate mask tables by running a setup script setup_ip.sh in the directory. Detailed instructions are also available in the submodule repository.

The same class CW305ShellExampleAES128BitRTL can be used to run the encryption with the design but don't forget to set implementation="google" or implementation="rsm" argument when con method is called.

HLS implementations of AES 128-bit encryption

First, you need to create an IP package from the HLS source code. In examples/aes128_hls directory, a script to create an IP package is available.

cd examples/aes128_hls
sh create_hls_ip.sh

It will create an IP package in examples/aes128_hls/hls_cw305_aes_enc. The target frequency is set to 20 MHz in the script, but you can change it.

After creating a project with the template, as described above, you can create a block design by running the following command in the Vivado Tcl console.

source <path to this repo>/examples/aes128_hls/create_bd.tcl

To run the encryption with the design, please use CW305ShellExampleAES128BitHLS class in the ChipWhisperer Plugin.

Another HLS implementation of AES 128-bit encryption is available in examples/aes128_hls_rsm, which is a protected version of the AES encryption by RSM masking scheme. IP package creation and block design creation are the same as the above. But don't forget to set implementation="rsm" argument when con method is called.

Misc.

This repository includes a base constraint file for the CW305 board. It specifies all the IO pins of the FPGA and on-board peripherals according to the schematic. However, pins which are not used in the shell design are not tested.

License

This repository is licensed under MIT License, see LICENSE for more information.

Similar projects

• SAKURA-X shell - A shell template for SAKURA-X FPGA