From e82a6e4ef63ccace38a8708d0c64cb66499e2d67 Mon Sep 17 00:00:00 2001 From: Pascal Nasahl Date: Tue, 17 Sep 2024 16:07:12 +0200 Subject: [PATCH] [doc] Update Bitstream Building Tutorial This commit updates the instructions how to build the FPGA bitstream for CW310. Moreover, the instructions how to compile the pen. testing framework is replaced with a link to the OpenTitan repository. Signed-off-by: Pascal Nasahl --- doc/building_fpga_bitstreams.md | 100 ++++++++++++++++++++++++++++ doc/getting_started.md | 111 +++----------------------------- 2 files changed, 109 insertions(+), 102 deletions(-) create mode 100644 doc/building_fpga_bitstreams.md diff --git a/doc/building_fpga_bitstreams.md b/doc/building_fpga_bitstreams.md new file mode 100644 index 00000000..2eaffcf8 --- /dev/null +++ b/doc/building_fpga_bitstreams.md @@ -0,0 +1,100 @@ +# Building FPGA Bitstreams for OT-SCA + +The idea of this tutorial is to document how to build FPGA bitstreams that can +be used for performing side-channel analysis on the ChipWhisperer boards using +ot-sca. + +## Prerequisites + +Bitstreams are created inside the [OpenTitan](https://github.com/lowRISC/OpenTitan) +repository. Make sure to follow the getting started +[guide](https://opentitan.org/book/doc/getting_started/index.html) before attempting +to build bitstreams. A Xilinx Vivado installation with a valid license is needed. + +Then, clone the OpenTitan repository and select a suitable commit. Make sure that +the selected commit is compatible with the penetration testing +[framework](https://github.com/lowRISC/opentitan/tree/master/sw/device/tests/penetrationtests). +When using the latest commit available in the OpenTitan master branch, the framework +and the FPGA bitstream should be compatible. + + +## Building CW310 Bitstreams + +For SCA measurements on the CW310, different bitstreams are available. + +| Name | Description | +|--------------------------------------------------------|----------------------------------------------------------------------------------------------------------| +| lowrisc_systems_chip_earlgrey_cw310_0.1_X.bit | Default bitstream. AES RTL is modified to raise a hardware-based trigger signal for SCA measurements. | +| lowrisc_systems_chip_earlgrey_cw310_0.1_kmac_dom_X.bit | Enables DOM masking for KMAC. Removes some blocks (e.g., OTBN) to save resource utilization on the FPGA. | +| lowrisc_systems_chip_earlgrey_cw310_0.1_ecdsa_X.bit | | + +The table above highlights the difference between each bitstream. X denotes the +hardware version, e.g., Z1 or A1. + +### Building the Default CW310 Bitstream + +To build the default bitstream, change the following parameters marked in +bold in the +[chip_earlgrey_cw310.sv](https://github.com/lowRISC/opentitan/blob/master/hw/top_earlgrey/rtl/autogen/chip_earlgrey_cw310.sv) +file: + +
+  top_earlgrey #(
+    .SecAesMasking(1'b1),
+    .SecAesSBoxImpl(aes_pkg::SBoxImplDom),
+    .SecAesStartTriggerDelay(320),
+    .SecAesAllowForcingMasks(1'b1),
+    .CsrngSBoxImpl(aes_pkg::SBoxImplLut),
+    .OtbnRegFile(otbn_pkg::RegFileFPGA),
+    .SecOtbnMuteUrnd(1'b1),
+    .SecOtbnSkipUrndReseedAtStart(1'b0),
+    .OtpCtrlMemInitFile(OtpCtrlMemInitFile),
+    .RvCoreIbexPipeLine(1),
+    .SramCtrlRetAonInstrExec(0),
+    .UsbdevRcvrWakeTimeUs(10000),
+    .KmacEnMasking(0),
+    .KmacSwKeyMasked(1),
+    .KeymgrKmacEnMasking(0),
+    .SecKmacCmdDelay(320),
+    .SecKmacIdleAcceptSwMsg(1'b1),
+    .RomCtrlBootRomInitFile(BootRomInitFile),
+    .RvCoreIbexRegFile(ibex_pkg::RegFileFPGA),
+    .RvCoreIbexSecureIbex(0),
+    .SramCtrlMainInstrExec(1),
+    .PinmuxAonTargetCfg(PinmuxTargetCfg)
+```
+
+ +With these hardware changes, the AES and KMAC IP block delay the start of the +operation by 320 cycles, giving Ibex enough time to go into the sleep mode. +Moreover, the KMAC IP block is configured to accept writes to the KMAC message +FIFO before triggering the operations. Finally, OTBN is configured in such a way +that PRNG reseeds are skipped at the OTBN application start. + +After making these hardware changes, use the following command to retrieve the +bitstream: + +```console +./bazelisk.sh build //hw/bitstream/vivado:fpga_cw310_test_rom +``` + +The bitstream is located in +```console +bazel-bin/hw/bitstream/vivado/build.fpga_cw310/synth-vivado/lowrisc_systems_chip_earlgrey_cw310_0.1.bit +``` +and can be copied into the `objs/` directory of ot-sca. + +### Building the KMAC DOM CW310 Bitstream + +### Building the ECDSA CW310 Bitstream + +## Building CW305 Bitstreams + +#TODO(lowrisc/ot-sca#377): Add instructions how to build bitstreams for CW305. + +## Pushing Bitstreams to OT-SCA + +When pushing bitstream to the ot-sca repository, please make sure: +- To include the git commit hash used for building the bitstream in the commit message. +- That the bitstream is compatible with the penetration testing firmware. +- That the bitstream is tracked in git lfs and is not pushed in plain. diff --git a/doc/getting_started.md b/doc/getting_started.md index 9a48d039..e67ffbc7 100644 --- a/doc/getting_started.md +++ b/doc/getting_started.md @@ -270,111 +270,18 @@ Capturing: 100%|█████████████████████ Created plot with 10 traces: ~/ot-sca/cw/projects/sample_traces_aes.html ``` +### Generating Bitstreams for OT-SCA -### Generating OpenTitan Binaries +If you want to build the bitstreams by yourself instead of using the pre-build +ones stored in `objs/`, please follow this [guide](./building_fpga_bitstreams.md). -Instead of using the example binaries provided by this repository via Git LFS, -you can regenerate them from the -[OpenTitan](https://github.com/lowRISC/OpenTitan) repository. +### Building the Penetration Testing Framework -Below, we quickly outline the necessary steps for building the binaries for the -CW310 and CW305 boards from the sources. For more information on the build -steps, refer to the [OpenTitan FPGA documentation](https://docs.opentitan.org/doc/ug/getting_started_fpga/). - -Note that below we use `$REPO_TOP` to refer to the main OpenTitan repository -top, not this `ot-sca` repo. - -#### Earl Grey for CW310 - -To build the binaries for performing SCA on the full Earl Grey top level of -OpenTitan using the CW310, follow these steps: - -1. Go to the root directory of the OpenTitan repository. -1. Build the regular binaries with - ```console - $ cd $REPO_TOP - $ ./bazelisk.sh build //sw/... - ``` -1. Then, the bitstream generation can be started by running - ```console - $ . /tools/xilinx/Vivado/2020.2/settings64.sh - $ cd $REPO_TOP - $ fusesoc --cores-root . run --flag=fileset_top --target=synth lowrisc:systems:chip_earlgrey_cw310 - ``` - The generated bitstream can be found in - ``` - build/lowrisc_systems_earlgrey_cw310_0.1/synth-vivado/lowrisc_systems_chip_earlgrey_cw310_0.1.bit - ``` - and will be loaded to the FPGA using the ChipWhisperer Python API. - -1. To generate the OpenTitan application binary (simpleserial interface), e.g., - for recording AES power traces on the CW310, run - ```console - $ cd $REPO_TOP - $ ./bazelisk.sh build //sw/device/sca:aes_serial - ``` - The path to the generated binary is: - ``` - $REPO_TOP/bazel-bin/sw/device/sca/ - ``` - To generate the OpenTitan application binary for uJSON that includes all SCA - targets, run - ```console - $ cd $REPO_TOP - $ ./bazelisk.sh build //sw/device/tests/crypto/cryptotest/firmware:firmware - ``` - -#### English Breakfast for CW305 - -To build the binaries for performing SCA of e.g. AES on the reduced English -Breakfast top level of OpenTitan using the CW305, follow these steps: - -1. Go to the root directory of the OpenTitan repository. -1. Before generating the OpenTitan FPGA bitstream for the CW305 target board, you first have to run: - ```console - $ cd $REPO_TOP - $ ./util/topgen-fusesoc.py --files-root=. --topname=top_englishbreakfast - ``` - to generate top-level specific versions of some IP cores such as RV_PLIC, - TL-UL crossbars etc. -1. Then run - ```console - $ cd $REPO_TOP - $ ./hw/top_englishbreakfast/util/prepare_sw.py --build --top=englishbreakfast - ``` - in order to prepare the OpenTitan software build flow for English - Breakfast and build the required binaries. More precisely, this script - runs some code generators, patches some auto-generated source files and - finally generates the boot ROM needed for bitstream generation. -1. Finally, the bitstream generation can be started by running - ```console - $ cd $REPO_TOP - $ fusesoc --cores-root . run --flag=fileset_topgen --target=synth lowrisc:systems:chip_englishbreakfast_cw305 - ``` - The generated bitstream can be found in - ``` - build/lowrisc_systems_chip_englishbreakfast_cw305_0.1/synth-vivado/lowrisc_systems_chip_englishbreakfast_cw305_0.1.bit - ``` - and will be loaded to the FPGA using the ChipWhisperer Python API. - -1. To generate the OpenTitan application binary for recording AES power traces, - make sure the `prepare_sw.py` script has been run before executing - ```console - $ cd $REPO_TOP - $ ./bazelisk.sh build //sw/device/sca:aes_serial --copt=-DOT_IS_ENGLISH_BREAKFAST_REDUCED_SUPPORT_FOR_INTERNAL_USE_ONLY_ - ``` -1. The path to the generated binary will be printed to the terminal after running - ```console - $ cd $REPO_TOP - $ ci/scripts/target-location.sh //sw/device/sca:aes_serial - ``` - -If you need to generate binaries for CW310 after you generate binaries for -CW305, use the following command: -```console -$ ./hw/top_englishbreakfast/util/prepare_sw.py --delete -``` -and clean the auto-generated files with a checkout. +Similarly, to build the penetration testing framework, please follow the +[guide](https://github.com/lowRISC/opentitan/tree/master/sw/device/tests/penetrationtests) +in the OpenTitan repository. For the FPGA framework, place the generated `.bin` +into the `objs/` directory. For the chip framework, the `.img` files need to be +used. ## Configuration