Overview

New to ChipWhisperer? No problem!

This page will give a brief overview of what ChipWhisperer is, where you can find documentation about different parts of the ChipWhisperer toolchain, as well as some of the major changes that have recently happened to ChipWhisperer.

Consider this page the answer to “Help, I’m confused… there are too many websites that have resources related to ChipWhisperer”.

What is ChipWhisperer?

ChipWhisperer is a complete open source toolchain for learning about side channel attacks on embedded devices and validating the side channel resistance of these devices. In particular, ChipWhisperer focuses on power analysis, which uses information leaked by a device’s power consumption to mount an attack, as well as voltage and clock glitching attacks, which briefly disrupt a device’s power or clock to cause unintended behaviour (such as skipping a password check).

Components

In total, ChipWhisperer has four layers of open source components:

Hardware

ChipWhisperer has scope boards, which are used to mount side channel attacks, as well as target boards, which function as a device under test (DuT). Hardware documentation can be found at https://rtfm.newae.com

Hardware is for the most part open source and design files/schematics can be found either on the ChipWhisperer Github repository, or on a UFO target board repository.

Firmware

ChipWhisperer also includes open source firmware for both scopes and targets.

Scope firmware is written in Verilog (for the FPGA) and C (USB microcontroller) and can be found in the hardware/capture sections of the ChipWhisperer Github repository.

Target firmware is mostly written in C (though we do have a few FPGA targets with code in Verilog) and can be found in the hardware/victims/firmware directory of the ChipWhisperer Github repository.

Software

ChipWhisperer has an open source Python library for controlling the capture hardware and communicating with the target. ChipWhisperer ReadTheDocs (this website) has the API documentation and installation instructions for this part of the ChipWhisperer toolchain.

The source code for the API is located on the ChipWhisperer Github repository.

Tutorials

Finally, ChipWhisperer also includes Jupyter Notebook tutorials and labs that both teach about side channel attacks that can be performed with ChipWhisperer, as well as showcase how to use the Python API. These tutorials/labs are available in the ChipWhisperer Jupyter Github repository. Some tutorials are also available as a completed static webpage over on the tutorials page.

Major Changes

There were some major changes related to where resources are located and in what format, after ChipWhisperer 5.1.0 was released. A more detailed version of the version changes also exists. Here are some of the major changes we are most excited about:

  • We changed our interface from the QT Graphical User Interface (GUI) we had before to using Jupyter Notebook. Keeping the GUI usable required a lot of effort, and since we are a small team it often meant bugs stayed around much too long. Also the change gave us a chance to make our Python API much more usable. Our project is open-source, and you are free to modify the software to meet your needs, however before the change this was sometimes quite difficult. We have not completely fixed the internals of the software but the new, documented API should make customization to your needs a whole lot easier.

  • We now have a documented Python API. You can actually read what functions and classes do, and this API should stay reliable in between minor version changes. Anything not documented in the API is not guaranteed to stay backwards compatible. This allows us the freedom to make improvements to the internals while you have a usable API.

  • We switched to Python 3, finally. This completely breaks all backwards compatibility with previous versions (less than 5.0.0), if we had not already done that will all of our changes.

  • We have this site now. The installation procedure, the software documentation, and the tutorials are on this site. We’ve now got a separate site for hardware docs as well. This site will be version based on releases of the software. Thank you readthedocs!

  • Tutorials are now auto-generated with our tutorial build system. The jupyter notebooks that are included in the ChipWhisperer GitHub repository in the jupyter submodule are built with multiple different types of hardware. The output is on the tutorials page of this site. Just like when you complete the tutorials some of the tutorials will contain output with warnings during the capture of power traces. This will make it easier to know what to expect when running the tutorials yourself.