HAWKEYE Artifacts

These are the artifacts for the Crypto'24 publication titled "HAWKEYE - Recovering Symmetric Cryptography From Hardware Circuits" by Gregor Leander, Christof Paar, Julian Speith, and Lukas Stennes.

Contents

This archive does not contain the HAWKEYE algorithm itself, but only our evaluation benchmarks and scripts. For the implementation of HAWKEYE, please refer to the GitHub repository of the netlist analysis framework HAL. These artifacts have been verified to work with HAL in version v4.4.1. Click here to directly get to the HAWKEYE plugin.

The structure of the archive is as follows:

• benchmarks: Contains all files related to the benchmark netlists used for evaluation, i.e., the respective netlist files and files specifying the ground truth to test against.
• scripts: Contains all scripts needed to reproduce our evaluation.
• sbox-database.json: A database of known S-boxes.

Prerequisites

HAWKEYE is shipped as part of HAL, which officially supports Ubuntu 22.04 LTS and 24.04 LTS. The artifacts have also been verified to work correctly on macOS (MacBook Pro with M2 CPU), but setting up HAL on macOS can sometimes be a bit delicate. We strongly advise not to use a virtual machine for runtime reasons.

Running HAWKEYE

1. To run HAWKEYE, you first need to clone and build HAL. To this end, please refer to the HAL Wiki. Please make sure to set -DBUILD_ALL_PLUGINS=ON when calling cmake to make sure that HAWKEYE is included in the HAL build (it is disabled by default). For your convenience, please find the commands to run below:
   • git clone https://github.com/emsec/hal.git && cd hal
   • git checkout v4.4.1
   • ./install_dependencies.sh
   • mkdir build && cd build
   • cmake .. -DBUILD_ALL_PLUGINS=ON
   • make
2. OpenTitan Case-Study:
   1. To re-run the OpenTitan case study, open the HAL GUI by calling bin/hal -g from the HAL build folder.
   2. Import benchmarks/netlists_fpga/open_titan/open_titan.hal by dragging the file into the OPEN PROJECT box in the middle of the welcome screen or using File->Import->Import Netlist and navigating to the right location.
   3. In the Netlist Import dialogue, leave everything as is (unless you want to change the project location) and press OK.
   4. Wait until HAL opened the netlist. As it is quite large, this may take some time (up to a few minutes). After opening the netlist, do NOT double-click or unfold the top_module box in the middle of the screen, as HAL will freeze otherwise.
   5. From the Python editor on the right side of HAL, open scripts/detect_on_current_netlist.py and run the script using the button depicting a green triangle.
   6. Wait until script execution has finished. Depending on your hardware, this may take a couple minutes.
   7. You should be able to see some output in the Python console in the lower right corner of HAL. The first line should contain the number of discovered candidates (25) and their sizes. Afterwards, each line represents one of the candidates as (i) its size and (ii) a randomly selected gate from its output register. These gates have been used to manually verify what part of the OpenTitan the respective candidate corresponds to. You should be able to match these results with the information displayed in Table 2 of the paper.
3. SoC Benchmarks:
   1. Adjust the paths in scripts/run_soc_benchmarks.py to the correct location using absolute paths.
   2. To run the SoC evaluations, execute the command bin/hal --python-script [...]/scripts/run_soc_benchmarks.py from the HAL build folder after adjusting the path.
   3. The script will automatically run HAWKEYE on all SoC, thereby reproducing the results from Table 3.

* The script executes the SoC benchmarks first using Method 1 (config with CHECK_PINS and CHECK_NETS) and then Method 2 (config with CHECK_TYPE and CHECK_SCC).
* The output for each benchmark will be formatted as [benchmark name] number_of_candidates_found: number_of_true_positives, number_of_false_positives, identified_S-box, candidate_sizes.
* unidentified S-box means that the implementation does contain an S-box, but HAWKEYE did not detect it. has no S-box means that the implementation does not feature an S-box.
4. Isolated Benchmarks:
1. Adjust the paths in scripts/run_isolated_benchmarks.py to the correct location using absolute paths.
2. To run the SoC evaluations, execute the command bin/hal --python-script [...]/scripts/run_isolated_benchmarks.py from the HAL build folder after adjusting the path.
3. The script will automatically run HAWKEYE on all isolated crypto and noise benchmarks, thereby reproducing the results from Table 4. Please note that this may take some time, but you should see constant progress in the console from which you started the script. The output is similar to the one for the SoC benchmarks.

Deviations from paper

After applying some fixes to our artifacts, we noticed the following deviations from the results reported in our paper:
* For ASCON on FPGA, we now find 1 false positive when using Method 1 instead of 0 false positives as reported before.
* For PRINCE on FPGA, we now find 0 false positives when using Method 1 instead of 1 false positive as reported before.
* For TRIVIUM_32 on FPGA, we now find 0 false positives when using Method 2 instead of 1 false positive as reported before.
* For Magma on ASIC, we now find 0 true positives when using Method 1 instead of 1 true positive as reported before.