From 3b6a1f6ec9ee9f728a098a5031522a7ee5e6a70a Mon Sep 17 00:00:00 2001 From: Pascal Nasahl Date: Fri, 26 Sep 2025 14:32:55 +0200 Subject: [PATCH] [doc] Update getting started As the getting started documentation was heavily outdated, this PR updates it accordingly. Signed-off-by: Pascal Nasahl --- doc/getting_started.md | 566 +++++++++++--------------------- doc/img/aes_capture_traces.png | 3 + doc/img/aes_traces.jpg | 3 - doc/img/aes_tvla_no_masks.png | 3 + doc/img/aes_tvla_with_masks.png | 3 + doc/img/fi_ibex.png | 3 + doc/img/kmac_traces.jpg | 3 - doc/img/sample_traces_aes.png | 3 - doc/img/sample_traces_kmac.png | 3 - doc/img/sample_traces_sha3.png | 3 - doc/img/sha3_traces.jpg | 3 - 11 files changed, 200 insertions(+), 396 deletions(-) create mode 100644 doc/img/aes_capture_traces.png delete mode 100644 doc/img/aes_traces.jpg create mode 100644 doc/img/aes_tvla_no_masks.png create mode 100644 doc/img/aes_tvla_with_masks.png create mode 100644 doc/img/fi_ibex.png delete mode 100644 doc/img/kmac_traces.jpg delete mode 100644 doc/img/sample_traces_aes.png delete mode 100644 doc/img/sample_traces_kmac.png delete mode 100644 doc/img/sample_traces_sha3.png delete mode 100644 doc/img/sha3_traces.jpg diff --git a/doc/getting_started.md b/doc/getting_started.md index ae357c00..e0d76551 100644 --- a/doc/getting_started.md +++ b/doc/getting_started.md @@ -4,22 +4,19 @@ ### Hardware Requirements -To perform side-channel analysis (SCA) for [OpenTitan](https://github.com/lowRISC/OpenTitan) -using the infrastructure provided in this repository, the following hardware -equipment is required: +To perform side-channel analysis (SCA) for [OpenTitan](https://github.com/lowRISC/OpenTitan) using the infrastructure provided in this repository, the following hardware equipment is required: * [ChipWhisperer CW310 FPGA Board with K410T](https://rtfm.newae.com/Targets/CW310%20Bergen%20Board//) - This is the target board. The Xilinx Kintex-7 FPGA is used to implement - the full Earl Grey top level of OpenTitan. Note that there are different - versions of the board available of which the board with the bigger FPGA - device (K410T) is required. + This is the target board. + The Xilinx Kintex-7 FPGA is used to implement the full Earl Grey top level of OpenTitan. + Note that there are different versions of the board available of which the board with the bigger FPGA device (K410T) is required. * [ChipWhisperer-Husky CW1190 Capture Board](https://github.com/newaetech/ChipWhisperer-Husky) - This is the capture or scope board. It is used to capture power traces of - OpenTitan implemented on the target board. The capture board comes with - SMA and 20-pin ChipWhisperer cable required to connect to the target board. + This is the capture or scope board. + It is used to capture power traces of OpenTitan implemented on the target board. + The capture board comes with SMA and 20-pin ChipWhisperer cable required to connect to the target board. The following, alternative hardware equipment is no longer supported: @@ -27,63 +24,49 @@ The following, alternative hardware equipment is no longer supported: This is a smaller target board than the CW310. - **Note:** The Xilinx Artix-7 A100T FPGA on the CW305-A100 is considerably - smaller than the Kintex-7 K410T FPGA on the CW310 and does not offer - sufficient resources for implementing the full Earl Grey top level of - OpenTitan. However, it is suitable for implementing the English Breakfast - top level, a substantially reduced version of OpenTitan. As a result, the - CW305-A100 is suitable for performing SCA of AES but not KMAC or OTBN. Note - that also for this board there exist different versions of which of which - only the board with the bigger FPGA device (XC7A100T-2FTG256) is supported. + **Note:** The Xilinx Artix-7 A100T FPGA on the CW305-A100 is considerably smaller than the Kintex-7 K410T FPGA on the CW310 and does not offer sufficient resources for implementing the full Earl Grey top level of OpenTitan. + However, it is suitable for implementing the English Breakfast top level, a substantially reduced version of OpenTitan. + As a result, the CW305-A100 is suitable for performing SCA of AES but not KMAC or OTBN. + Note that also for this board there exist different versions of which only the board with the bigger FPGA device (XC7A100T-2FTG256) is supported. **Support:** Older versions of the repo support this target. ### Hardware Setup -To setup the hardware, first connect the target and capture board together. You -don't want to accidentally short something out with the conductive SMA -connector. +To setup the hardware, first connect the target and capture board together. +You don't want to accidentally short something out with the conductive SMA connector. #### CW310 As shown in the photo below, -1. Connect the `SHUNTLOW AMPLIFIED` output of the CW310 (topmost SMA) to the - CW-Husky `Pos` input. -1. Connect the `ChipWhisperer Connector` (`J14`) on the CW310 to the - `ChipWhisperer 20-Pin Connector` on the capture board. On the CW-Husky this - is the connector on the *SIDE* not the connector on the *FRONT*. +1. Connect the `SHUNTLOW AMPLIFIED` output of the CW310 (topmost SMA) to the CW-Husky `Pos` input. +1. Connect the `ChipWhisperer Connector` (`J14`) on the CW310 to the `ChipWhisperer 20-Pin Connector` on the capture board. + On the CW-Husky this is the connector on the *SIDE* not the connector on the *FRONT*. ![](img/cw310_cwhusky.jpg) -The CW310 will need a power supply, the default power supply uses a DC barrel -connector to supply 12V. If you use this power supply all switches should be -in the default position. To this end, make sure to: -1. Set the `SW2` switch (to the right of the barrel connector) up to the - `5V Regulator` option. -1. Set the switch below the barrel connector to the right towards the `Barrel` - option. +The CW310 will need a power supply, the default power supply uses a DC barrel connector to supply 12V. +If you use this power supply all switches should be in the default position. +To this end, make sure to: +1. Set the `SW2` switch (to the right of the barrel connector) up to the `5V Regulator` option. +1. Set the switch below the barrel connector to the right towards the `Barrel` option. 1. Set the `Control Power` switch (bottom left corner, `SW7`) to the right. -1. Ensure the `Tgt Power` switch (above the fan, `S1`) is set to the right - towards the `Auto` option. +1. Ensure the `Tgt Power` switch (above the fan, `S1`) is set to the right towards the `Auto` option. Then, -1. Plug the DC power adapter into the barrel jack (`J11`) in the top left - corner of the board. -1. Use a USB-C cable to connect your PC with the `USB-C Data` connector (`J8`) - in the lower left corner on the board. +1. Plug the DC power adapter into the barrel jack (`J11`) in the top left corner of the board. +1. Use a USB-C cable to connect your PC with the `USB-C Data` connector (`J8`) in the lower left corner on the board. 1. Connect the CW-Husky to your PC via USB-C cable. -You should see the blue "Status" LED on the CW310 blinking, along with several -green power LEDs. The "USB-C Power" led may be red as there is no USB-C PD -source. The CW-Husky should also have a green blinking status LED at this -point. If LEDs are solid it may mean the device has not enumerated, which might -require additional setup (see UDEV Rules below). +You should see the blue "Status" LED on the CW310 blinking, along with several green power LEDs. +The "USB-C Power" led may be red as there is no USB-C PD source. +The CW-Husky should also have a green blinking status LED at this point. +If LEDs are solid it may mean the device has not enumerated, which might require additional setup (see UDEV Rules below). ### UDEV Rules -You might need to setup the following `udev` rules to gain access to the two -USB devices. To do so, open the file `/etc/udev/rules.d/90-lowrisc.rules` or -create it if does not yet exist and add the following content to it: +You might need to setup the following `udev` rules to gain access to the two USB devices. +To do so, open the file `/etc/udev/rules.d/90-lowrisc.rules` or create it if does not yet exist and add the following content to it: ``` # CW310 (Kintex Target) @@ -99,25 +82,18 @@ $ sudo udevadm control --reload ``` and then disconnect and reconnect the devices. -With the optional `SYMLINK` attribute, a stable symbolic link is created, -helping to identify the USB devices more easily. +With the optional `SYMLINK` attribute, a stable symbolic link is created, helping to identify the USB devices more easily. -For more details on how to set up `udev` rules, see the corresponding section -in the [OpenTitan documentation](https://docs.opentitan.org/doc/ug/install_instructions/#xilinx-vivado). +For more details on how to set up `udev` rules, see the corresponding section in the [OpenTitan documentation](https://docs.opentitan.org/doc/ug/install_instructions/#xilinx-vivado). ### Software Requirements -Software required by this repository can either be directly installed on a -machine or obtained using the provided [Dockerfile](https://github.com/lowRISC/ot-sca/blob/master/util/docker/Dockerfile). +Software required by this repository can be directly installed on your computer. +We recommend using Ubuntu 22.04 or 24.04, other Linux versions might work as well. +#### Python Virtual Environment -#### Installing on a Machine - -##### Python Virtual Environment - -To avoid potential dependency conflicts (in particular with the main OpenTitan -repository which may be using a different version of ChipWhisperer) it is -strongly recommended to setup a virtual Python environment for this repository. +To avoid potential dependency conflicts (in particular with the main OpenTitan repository which may be using a different version of ChipWhisperer) it is strongly recommended to setup a virtual Python environment for this repository. To this end, type ```console @@ -132,11 +108,10 @@ $ source .venv/bin/activate to enable the virtual environment previously initialized. -##### Python Dependencies +#### Python Dependencies -This repository has a couple of Python dependencies to be installed through -`pip`. It is recommended to first install the latest version of `pip` and -`setuptools` using +This repository has a couple of Python dependencies to be installed through `pip`. +It is recommended to first install the latest version of `pip` and `setuptools` using ```console python3 -m pip install -U pip "setuptools<66.0.0" ``` @@ -147,27 +122,23 @@ $ pip install -r python-requirements.txt to install all the required Python dependencies. -##### ChipWhisperer Dependencies +#### ChipWhisperer Dependencies -ChipWhisperer itself is installed as a Python dependency through -`python_requirements.txt`. +ChipWhisperer itself is installed as a Python dependency through `python_requirements.txt`. -However, it has some non-Python dependencies related to USB. Please see -[this page](https://chipwhisperer.readthedocs.io/en/latest/linux-install.html#required-packages) -to install the specific `apt` packages required by ChipWhisperer. +However, it has some non-Python dependencies related to USB. +Please see [this page](https://chipwhisperer.readthedocs.io/en/latest/linux-install.html#required-packages) to install the specific `apt` packages required by ChipWhisperer. **Notes:** - We recommend to use Python 3.10. Later versions might also work. -- CW-Husky requires ChipWhisperer 5.7.0 or later. The default - `python_requirements.txt` will install a version supporting CW-Husky. +- CW-Husky requires ChipWhisperer 5.7.0 or later. + The default `python_requirements.txt` will install a version supporting CW-Husky. -##### Git Large File Storage (LFS) +#### Git Large File Storage (LFS) -This project uses Git LFS for storing binaries like example target FPGA -bitstreams on a remote server. The repository itself just contains diff-able -text pointers to the binaries. It is recommended to install the `git-lfs` -tool for transparently accessing the binaries. Alternatively, they can be -downloaded manually from GitHub. +This project uses Git LFS for storing binaries like example target FPGA bitstreams on a remote server. +The repository itself just contains diff-able text pointers to the binaries. It is recommended to install the `git-lfs` tool for transparently accessing the binaries. +Alternatively, they can be downloaded manually from GitHub. You can run ```console @@ -181,202 +152,75 @@ $ git-lfs pull ``` to get the binaries. -Alternatively, you can rebuild those binaries yourself from the -[OpenTitan](https://github.com/lowRISC/OpenTitan) repository. - - -#### Using the Docker Image - -**Notes**: -- While the provided container image can be run using the Docker Engine, this - getting started guide relies on Podman instead to avoid requiring root - permissions on the host. -- This is a WIP and currently supports Linux hosts only. - -The -[Dockerfile](https://github.com/lowRISC/ot-sca/blob/master/util/docker/Dockerfile) -in this repository can be used to build a ready-to-use image with all the -dependencies installed. To build the image: -1. If not already installed, install Podman and containers-storage following the instructions -[here](https://podman.io/getting-started/installation), and -2. Build the container image using -[build\_image.sh](https://github.com/lowRISC/ot-sca/blob/master/util/docker/build_image.sh): -```console -$ util/docker/build_image.sh -``` - -Once the image is built, you can run it using -[run\_container.sh](https://github.com/lowRISC/ot-sca/blob/master/util/docker/run_container.sh): -```console -$ util/docker/run_container.sh -h - -Run OpenTitan SCA/FI image. - -Usage: util/docker/run_container.sh -d DEVICE [-d DEVICE] -m SHM_SIZE -w HOST_WORK_DIR [-h] - - -d: Host device to be added to the container. This option can be used multiple times. - -m: Shared memory size (/dev/shm) of the container. Should be at least 1/3 of total memory. - -w: Host directory that will be mounted into the container as /repo - -h: Print usage information and exit. -``` - -For example, if the host has 32+ GB RAM, the ot-sca repository is at -`~/repos/ot-sca`, and ChipWhisperer devices are at `/dev/opentitan/cw_310` -and `/dev/opentitan/cw_husky`, you can use: -```console -$ util/docker/run_container.sh -d /dev/opentitan/cw_310 -d /dev/opentitan/cw_husky -m 12g -w ~/repos/ot-sca -``` - -If ChipWhisperer devices are the only USB devices that are connected to the -host, you can use the following to add all USB devices to the container: -```console -$ util/docker/run_container.sh $(find /dev/opentitan -type l -exec readlink -f {} \; | sed 's/^/-d /g' | xargs echo) -m 12g -w ~/repos/ot-sca -``` - -Once the container is running, try capturing some traces to verify that -everything is working correctly: -```console -Creating user 'ot' with UID=1000, GID=1000. -ot@ot-sca:/repo$ cd cw/ -ot@ot-sca:/repo/cw$ ./capture.py --cfg-file capture_aes_cw310.yaml capture aes-random -Connecting and loading FPGA... Done! -Initializing PLL1 -Programming OpenTitan with "objs/aes_serial_fpga_cw310.bin"... -Transferring frame 0x00000000 @ 0x00000000. -Transferring frame 0x00000001 @ 0x000007D8. -Transferring frame 0x00000002 @ 0x00000FB0. -Transferring frame 0x00000003 @ 0x00001788. -Transferring frame 0x00000004 @ 0x00001F60. -Transferring frame 0x00000005 @ 0x00002738. -Transferring frame 0x80000006 @ 0x00002F10. -Scope setup with sampling rate 200009376.0 S/s -Reading from FPGA using simpleserial protocol. -Target simpleserial version: z01 (attempts: 1). -Using key: b'2b7e151628aed2a6abf7158809cf4f3c' -Capturing: 100%|████████████████████████████| 5000/5000 [00:55<00:00, 90.34it/s] -Created plot with 10 traces: ~/ot-sca/cw/projects/sample_traces_aes.html -``` - - -### Generating OpenTitan Binaries - -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. - -Below, we quickly outline the necessary steps for building the binaries for the -CW310 board 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/). +### Generating OpenTitan Binaries and Bitstreams -Note that below we use `$REPO_TOP` to refer to the main OpenTitan repository -top, not this `ot-sca` repo. +Instead of using the example binaries and bitstreams provided by this repository via Git LFS, you can regenerate them from the [OpenTitan](https://github.com/lowRISC/OpenTitan) repository. +This is needed if you want to develop your own, new SCA and FI tests. +For more information on the buildsteps, refer to the following [guide](./building_fpga_bitstreams_binaries.md). -#### Earl Grey for CW310 +## Side-Channel Analysis -To build FPGA bitstreams and penetration testing framework binaries for CW310, please follow this [guide](./building_fpga_bitstreams.md). +All the capture scripts for performing SCA on OpenTitan are available in the `capture/` directory. +There exist separate capture scripts and configuration files for each target (e.g., AES, HMAC, ...). -## Configuration +### Capturing Power Traces for AES on CW310 with Masking Disabled -The main configuration of the OpenTitan SCA setup is stored in the files +The following guideline shows how to capture AES power traces on the CW310. +The first step is to configure the experiment using the corresponding config file: ``` capture/configs/aes_sca_cw310.yaml ``` -for AES. -For example, these files allow to specify the FPGA bitstream to be loaded, the -OpenTitan application binary to execute, the default number of traces to -capture and the ADC gain. By default, the prebuilt binaries delivered with this -repository are used. If you want to use custom binaries, open the file and edit -the specified file paths. - -**Notes**: -* When working with custom binaries, it is recommended to always re-generate - both bitstream and application binaries from the OpenTitan repository. - Otherwise you might risk to end up with an incompatible combination of - bitstream and application binary. -* The default configurations target the CW310 board. - - -## Capturing Power Traces - -Our setup supports capturing AES, KMAC, SHA3 and OTBN power traces using a CW-Husky capture board. -The setup also supports capturing power traces in batches to achieve substantially higher capture rates. - -Before starting a long running capture, it is recommended to always perform a capture with fewer traces to make sure the setup is configured as expected (e.g. ADC gain). - -### AES Capture - -To perform a capture `capture/capture_aes.py` is used with default configurations set in the `*.yaml` files. -When using this script configuration file and project path need to be given as parameters. - -There are 4 capture modes for AES: -1. AES Random -1. AES Random Batch -1. AES Fixed vs Random Key -1. AES Fixed vs Random Key Batch - -Modes `aes_fvsr_key_batch` and `aes_fvsr_key` capture data for fixed-vs-random key analysis. -This analysis is described in DTR TVLA Section 5.3. "General Test: Fixed-vs.-Random Key Datasets". -In this data set two types of traces are collected, namely fixed (using a constant key) and random (using a randomly selected key). -Each measurement uses a randomly generated plaintext. -Measurements alternate between fixed and random, in a random manner (depending on a randomly generated bit). - -Modes `aes_random_batch` and `aes_random` capture data for random data analysis. -In this analysis, the key is constant for all measurements, and all plaintexts are randomly generated. - -The capture type can be configured by setting the `which test:` parameter in the configuration file. -This can be done by uncommenting the corresponding line. -``` - # which_test: aes_random_batch - # which_test: aes_random - which_test: aes_fvsr_key_batch - # which_test: aes_fvsr_key -``` - -To perform AES capture using any mode, you can use the following command: +This config file allows you to configure the following settings: +- target + - Specify the bitstream and the binary to load. + - You also can provide a dedicated `port:` that is used for the UART communication with the CW310 board. +- husky + - If you are using the ChipWhisperer Husky to capture power traces, you can specify the sampling rate and the scope gain. + - Moreover, you also can specify the number of clock cycles you want to capture and the offset before or after the trigger. +- waverunner + - If you are using a LeCroy oscilloscope instead, you additional can provide the IP address of the scope. +- capture + - Configure which scope you want to use. + - `num_segments` allows you to configure the number of batches for the batch mode. + - `num_traces` is the number of traces the capture script records. + - `trace_threshold` configures the number of traces that are stored in RAM before they are flushed to the disk. +- test + - Configure which test you want to run. + - Allows you to also enable / disable certain settings, like masking, dummy instructions and much more. + +For the example in this guideline, change the following parameters: +- `num_traces: 10000` +- `which_test: aes_fvsr_key` +- `lfsr_seed: 0` - this will disable masking + +Then run the script: ```console $ cd capture -$ ./capture_aes.py -c configs/aes_sca_cw310.yaml -p projects/aes_sca_cw310 -``` - -This script will load the OpenTitan FPGA bitstream to the target board, load and start the application binary to the target via SPI, and then feed data in and out of the target while capturing power traces on the capture board. -It should produce console output similar to the following output: - -```console +$ ./capture_aes.py -c configs/aes_sca_cw310.yaml -p aes_capture +INFO:root:Initializing target cw310 ... Initializing target cw310 ... Connecting and loading FPGA... Done! Initializing PLL1 Programming 256 bytes at address 0x00000000. -Programming 256 bytes at address 0x00000100. -Programming 256 bytes at address 0x00000200. ... -Programming 112 bytes at address 0x00009000. -Target simpleserial version: z01 (attempts: 1). -INFO:root:Initializing scope husky with a sampling rate of 200000000... -Initializing scope husky with a sampling rate of 200000000... +Programming 232 bytes at address 0x00028700. +INFO:root:Initializing scope husky with a sampling rate of 200000000... +Initializing scope husky with a sampling rate of 200000000... (ChipWhisperer Scope WARNING|File ChipWhispererHuskyClock.py:378) ADC frequency must be between 1MHz and 300000000.0MHz - ADC mul has been adjusted to 2 (ChipWhisperer Scope WARNING|File ChipWhispererHuskyClock.py:409) PLL unlocked after updating frequencies (ChipWhisperer Scope WARNING|File ChipWhispererHuskyClock.py:410) Target clock has dropped for a moment. You may need to reset your target -Connected to ChipWhisperer (num_samples: 501, num_samples_actual: 501, num_segments_actual: 1) -INFO:root:Setting up capture aes_random batch=True... -Setting up capture aes_random batch=True... -INFO:root:Initializing OT AES with key b'811e3731b0120a7842781e22b25cddf9' ... -Initializing OT AES with key b'811e3731b0120a7842781e22b25cddf9' ... -Capturing: 100%|██████████████████████| 1000/1000 [00:01<00:00, 807.02 traces/s] +Connected to ChipWhisperer (num_samples: 1200, num_samples_actual: 1200, num_segments_actual: 1) +INFO:root:Setting up capture aes_fvsr_key ... +Setting up capture aes_fvsr_key ... +Capturing: 100%|████████████████████| 10000/10000 [00:41<00:00, 240.02 traces/s] +INFO:root:Created plot with 100 traces: /home/nasahlpa/projects/ot_sca_doc_update/ot-sca/capture/aes_capture.html +Created plot with 100 traces: /home/nasahlpa/projects/ot_sca_doc_update/ot-sca/capture/aes_capture.html ``` -In case you see console output like -```console -WARNING:root:Your firmware is outdated - latest is 0.20. Suggested to update firmware, as you may experience errors -See https://chipwhisperer.readthedocs.io/en/latest/api.html#firmware-update -``` -you should update the firmware of one or both of the ChipWhisperer boards. -This process is straightforward and well documented online. -Simply follow the link printed on the console. - Once the power traces have been collected, a picture similar to the following should be shown in your browser. -![](img/aes_traces.jpg) +![](img/aes_capture_traces.png) Note the input data can range from `0` to `4095` (this is because ADC resolution on CW-Husky is 12 bits). If the output value is exceeding those limits you are clipping and losing data. @@ -384,157 +228,76 @@ But if the range is too small you are not using the full dynamic range of the AD You can tune the `scope_gain` setting in the `.yaml` configuration file. Note that boards have some natural variation, and changes such as the clock frequency, core voltage, and device utilization (FPGA build) will all affect the safe maximum gain setting. -### KMAC-128 Capture - -There are 3 capture modes for KMAC: -1. KMAC Random -1. KMAC Fixed vs Random Key -1. KMAC Fixed vs Random Key Batch +### TVLA Analysis for the Captured AES Power Traces on CW310 -The capture type can be configured by setting the `which test:` parameter in the configuration file. -This can be done by uncommenting the corresponding line. +As we have disabled masking in the example before, check if a TVLA test can detect the expected leakage. +For this, modify the following config file: ``` - # which_test: kmac_random - # which_test: kmac_fvsr_key - which_test: kmac_fvsr_key_batch +analysis/configs/aes_sca_cw310.yaml ``` - -To perform a KMAC-128 capture, use this command: +as following: +- `project_file: ../capture/aes_capture` +- `test_type: "GENERAL_KEY"` +- `trace_threshold: 10000` +then run the TVLA script: ```console -$ cd capture -$ ./capture_kmac.py -c configs/kmac_sca_cw310.yaml -p projects/kmac_sca_cw310 -``` - - -You should see similar output as in the AES example. -Once the power traces have been collected, a picture similar to the following should be shown in your browser. - -![](img/kmac_traces.jpg) +$ cd ../analysis +$ ./tvla.py --cfg-file configs/tvla_cfg_aes_specific_byte0_rnd0.yaml run-tvla +2025-09-26 10:59:10 INFO: Processing Step 1/1: Trace 0 - 9999 +2025-09-26 10:59:10 INFO: Converting Traces +2025-09-26 10:59:10 INFO: Will use samples from 0 to 1200 +2025-09-26 10:59:10 INFO: Filtering Traces +2025-09-26 10:59:10 INFO: Will use 8931 traces (89.3%) +2025-09-26 10:59:10 INFO: Computing Leakage +2025-09-26 10:59:10 INFO: Building Histograms +2025-09-26 10:59:11 INFO: Computing T-test Statistics +2025-09-26 10:59:12 INFO: Updating T-test Statistics vs. Number of Traces +2025-09-26 10:59:12 INFO: Leakage above threshold identified in the following order(s) marked with X +2025-09-26 10:59:12 INFO: Couldn't compute statistics for order(s) marked with O: +Order 1: X +Order 2: X -### SHA3 Capture - -There are 3 capture modes for SHA3: -1. SHA3 Random -1. SHA3 Fixed vs Random Data -1. SHA3 Fixed vs Random Data Batch - -To perform a SHA3 capture, use this command: -```console -$ cd capture -$ ./capture_sha3.py -c configs/sha3_sca_cw310.yaml -p projects/sha3_sca_cw310 +2025-09-26 10:59:12 INFO: Plotting Figures to tmp/figures +2025-09-26 10:59:12 INFO: Plotting T-test Statistics vs. Time. ``` - -You should see similar output as in the KMAC example. Once the power traces have -been collected, a picture similar to the following should be shown in your -browser. - -![](img/sha3_traces.jpg) - - -You can also use the batch mode with -```console -$ cd cw -$ ./capture.py --cfg-file capture_sha3_cw310.yaml capture sha3-fvsr-data-batch --num-traces 100 --plot-traces 10 +To view the TVLA plot, open: +``` +analysis/tmp/figures/aes_fixed_vs_random.png ``` -Errors might occur due to synchronization issues. In this case try to reset the board and -try again. - -To disable masking use the ```sha3_sca_cw310_masks_off_cw310.yaml``` file. The capture commands stay the same. - - - -### SHA3 TVLA +![](img/aes_tvla_no_masks.png) -Currently, we only support the general (non-specific) TVLA, which should only be used on a Fixed-vs.-Random -Dataset. To perform the analysis for the masked version, run: +### Capturing Power Traces for AES on CW310 with Masking Enabled -```console -$ cd cw -$ ./tvla.py --cfg-file tvla_cfg_sha3.yaml run-tvla +To verify that masking for the AES works, switch back to the `capture/` directory and modify: ``` - -For disabled masking run: -```console -$ cd cw -$ ./tvla.py --cfg-file tvla_cfg_sha3_masks_off.yaml run-tvla +capture/configs/aes_sca_cw310.yaml ``` +as following: +- `lfsr_seed: 0xdeadbeef` - -## Performing Example SCA Attack on AES with Masking Disabled - -The OpenTitan AES module uses boolean masking to aggravate SCA attacks. For -evaluating the SCA setup as well as specific attacks, the OpenTitan AES -module supports an FPGA-only compile-time Verilog parameter allowing software -to disable the masking. In the following example, we are going to disable the -masking in order to demonstrate an example attack. Note that On the ASIC, the -masking cannot be disabled. - -### Disabling Masking - -1. In the OpenTitan repository, edit the file `sw/device/sca/aes_serial.c` to - and change `.masking = kDifAesMaskingInternalPrng` to - `.masking = kDifAesMaskingForceZero`. -1. From the root directory of the OpenTitan repository, run +Now, again run the capture script: ```console -$ ./bazelisk.sh build //sw/... +$ ./capture_aes.py -c configs/aes_sca_cw310.yaml -p aes_capture_masks_on ``` - To re-generate the application binary. -### Configuration - -Open the config file `cw/capture_aes_cw310.yaml` and make sure to: -1. Change the path to application binary to use the one from the previous step. -1. If necessary, change the path to the bitstream to use a bitstream matching - The application binary. - -### Capturing Power Traces - -Run the following commands - -```console -$ cd cw -$ ./capture.py --cfg-file capture_aes_cw310.yaml capture aes-random-batch --num-traces 2000000 +Switch to the `analysis/` directory and modify: ``` -to start the capture. - -### Performing the Attack - -Run the following commands: - -```console -$ cd cw -$ ./ceca.py -f projects/opentitan_simple_aes.cwp -a 505 520 -d output -s 3 -w 16 -n 2000000 +analysis/configs/aes_sca_cw310.yaml ``` +as following: +- `project_file: ../capture/aes_capture_masks_on` -This should give you an output like this: +After again running the TVLA script: ```console -2021-10-23 13:19:19,846 INFO ceca.py:520 -- Will use 1962961 traces (98.1% of all traces) -2021-10-23 13:19:21,115 INFO _timer.py:61 -- compute_pairwise_diffs_and_scores took 0.4s -2021-10-23 13:19:21,116 INFO ceca.py:528 -- Difference values (delta_0_i): [ 0 196 41 120 25 62 245 89 49 239 220 24 102 179 220 118] -2021-10-23 13:19:21,158 INFO ceca.py:532 -- Recovered AES key: 2b7e151628aed2a6abf7158809cf4f3c -2021-10-23 13:19:21,159 INFO ceca.py:538 -- Recovered 82/120 differences between key bytes -2021-10-23 13:19:21,159 INFO _timer.py:61 -- perform_attack took 13.6s -2021-10-23 13:19:21,159 INFO _timer.py:61 -- main took 14.7s +$ ./tvla.py --cfg-file configs/tvla_cfg_aes_specific_byte0_rnd0.yaml run-tvla ``` +No leakage is visible in the TVLA plot: -The setting of `-n 2000000` is how many traces to use, if you receive a memory error reduce -the number of traces. - -The setting of `-a 505 520` specifies a location in the power traces, you may need to change -these settings with new FPGA builds as the leakage location will shift. - -### Debugging - -Run the following command to see serial outputs of the target program: - -```console -$ screen /dev/ttyACM1 115200,cs8,-ixon,-ixoff -``` -Note that you may need to change "ttyACM1" to something else. +![](img/aes_tvla_with_masks.png) -# Trace Preprocessing +### Trace Preprocessing The `analysis/trace_preprocessing.py` script allows the user to preprocess traces that were captured with the OpenTitan trace library. This script provides two functionalities: @@ -554,6 +317,53 @@ An example is shown below: $ ./trace_preprocessing.py -i db_in.db -o db_out.db -f -s 7.5 -a -p 5 -n 1000 -lw 21000 -hw 23000 -ms 20 -m 1000 -c 4 ``` +## Fault Injection + +OT-SCA currently supports voltage glitching and EMFI using the ChipWhisperer Husky and ChipShouter combined with the ChipShover XYZ table. +If you do not have a fault injection setup yet, you can try out running OT-SCA in the demo mode. + +### Ibex Fault Injection in the Demo Mode + +To perform a fault injection attack in the demo mode, i.e., without any FI gear attached, follow the following steps: + +```console +$ cp ci/cfg/ci_ibex_fi_vcc_dummy_cw310.yaml fault_injection/configs/ibex_fi_vcc_dummy_cw310.yaml +``` +Modify the following paramter in the copied file: +- `port: "/dev/ttyACM_CW310_1` +to point to the UART port of the CW310 board. + +```console +$ cd fault_injection +$ ./fi_ibex.py -c configs/ibex_fi_vcc_dummy_cw310.yaml -p ibex_fi +INFO:root:Initializing target cw310 ... +Initializing target cw310 ... +Connecting and loading FPGA... Done! +Initializing PLL1 +Programming 256 bytes at address 0x00000000. +... +Injecting: 0%| | 0/100 [00:00