Python Project hwpwn

While working on my latest Simple Power Analysis (SPA) experiment, I found myself frequently creating plots and engaging in trial-and-error with signal analysis. The purpose of SPA is to use power analysis to infer what is happening in the target, leaking information from the inside.

On multiple occasions, I wanted to tweak a parameter, re-run specific signal processing steps, and assess the results. Initially, I used Python scripts (or a single, large Python script) that I copied and named as needed. Although this approach might work for attacks with clear-cut requirements, it quickly becomes confusing for those involving extensive trial and error.

I developed a simple, reusable Python script to organize my various adjustments better. As I continued to add functionality, it made sense to restructure the code to enhance its scalability and user-friendliness. This idea led to the creation of hwpwn, my first Python package.

The hwpwn can be executed as a client tool:

$ hwpwn data load test.csv | hwpwn plot time

Which shows a pretty plot of the data:

In this case, the first command will load the test.csv file contents into a table structure and convert it to an internal format used by hwpwn. The file can be a signal capture from a USB oscilloscope.

In the previous example, test.csv contained:

t,a,b,c
1,3,3,4
2,3,4,5
3,9,2,1

Before finishing any command, hwpwn will check if the output is being piped. If yes, it will print the data to stdout in JSON format. This format is automatically ingested by piped hwpwn commands that follow.

In this case, the plot command will take the data from the previous command, passed by stdout. The plot time command will do a time-series plot of the data.

There are multiple configurable options, documented in hwpwn docs or in the command line directly:

$ hwpwn plot --help

 Usage: hwpwn plot [OPTIONS] COMMAND [ARGS]...

╭─ Options ─────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                   │
╰───────────────────────────────────────────────────────────────╯
╭─ Commands ────────────────────────────────────────────────────╮
│ butterhp                                                      │
│ freq       Frequency response plot for all signals.           │
│ phasecorr  Phase correlation analysis plot.                   │
│ time       Time-series plot of the data. The x-axis in the    │
│            data is used as the time-series axis for all the   │
│            signals and triggers. This command supports        │
│            providing multiple parameters but all are          │
│            optional.                                          │
│ xcorr      Cross-correlation plots between two signals.       │
│ xy                                                            │
╰───────────────────────────────────────────────────────────────╯

The hwpwn is using Typer Python package for handling command line, and it supports adding shell auto-completion. Refer to hwpwn --help for more information.

Alternatively, it can be imported by custom Python scripts where its functions are called directly. The package is available from pypi repository directly so it can be installed with pip:

$ pip install --user hwpwn

Then, a simple python script could be:

from hwpwn import data as hwd
from hwpwn import plot as hwp
hwd.load(filepath='test.csv', xscale=1)
hwp.time()

Custom operations on data can be done while using hwpwn.

from hwpwn import data as hwd
from hwpwn import plot as hwp
import numpy as np

d = hwd.load(filepath='test.csv', xscale=1)
d['signals'][0]['vector'] = np.subtract(d['signals'][0]['vector'], 3)
hwp.time(d)

Another way of executing hwpwn is through flow scripts. These are described in YAML format. For example, a test.yaml could contain:

---
options:
  scale: 1.0e-6
  ts: 4.0e-9
  description: |
    My description I'd like to include!    
operations:
  - data.load:
      filepath: test.csv
  - data.subtract:
      pos: a
      neg: b
      dest: ab
      append: true

To execute this flow simply use:

$ hwpwn flow run test.yaml

The structure of the flow in the file is simple and will call directly the commands available by the hwpwn cli. The idea in providing these multiple ways of using hwpwn is a big advantage to ease its use in multiple contexts.

The hwpwn’s capabilities are not yet comprehensive. However, I plan to keep expanding its features as I experiment with other physical attacks. Additionally, I have made the project open-source to encourage contributions from others. So please feel free to check it out in Github (here).