Installing ChipWhisperer

Python Setup

You may already have Python installed, in which case you can skip some of these steps. If you already have Python installed make sure it is the correct version (2.7.x). Python 3.x will not work with this codebase.

python setup.py install

pip install umysql

Getting & Installing ChipWhisperer

Assuming you've got a working Python installation, the next step is to install & run ChipWhisperer itself. This requires you to get a copy of ChipWhisperer, you should download the Latest Release. Download & unzip the file somewhere. Note if you are adventurous you can clone the GIT Repository git://git.assembla.com/chipwhisperer.git instead, but this may be broken so you should start with the latest release instead.

Generally 'somewhere' will become your ChipWhisperer working directory. These examples assume you've chosen C:\chipwhisperer as your working directory.

Once you've got the file, we run the Python install procedure again (setup.py). We slightly modify it to use the develop command to reflect that the files will probably be changing frequently. Again open a terminal and run the following, adjusting paths as needed:

cd c:\chipwhisperer\openadc\controlsw\python
python setup.py develop
cd c:\chipwhisperer\software
python setup.py develop

If you wish to confirm the installation worked, you can run ChipWhispererAnalyzer in the same terminal:

cd c:\chipwhisperer\software\chipwhisperer\
python CWAnalyzer.pyw

Alternatively you can just double-click on CWAnalyzer.py from Windows explorer, which should run the file using Python, provided you've registered Python to execute the .py extension.

You can see a Video of the Installation Procedure:

_

Installing Hardware Drivers

Details of driver installation are on specific pages for supported hardware (such as hwcapturerev2 and naecw1173_cwlite). Drivers are available from ChipWhisperer release section.

Getting AVR Compiler Toolchain

The following section is NOT REQUIRED for your first attack - you can jump right to the tutorial if you wish. However you'll ultimately wish to modify the code of the device under test, and these instructions tell you how. You should first follow the tutorial to confirm your system is working before modifying the code however!

To build the code, you'll need to install WinAVR on Windows (if using the Virtual Machine, the following is not required, as the VM comes setup with the AVR compiler already).

Note that the default codebase does not include the cryptographic code we attack. Instead you are required to add this code into the system -- if the external code changes, this may eventually be instead rolled into the main codebase. To setup the code, follow the following steps:

1. cd to the directory with the avr-serial example, and run make:

   cd c:\chipwhisperer\hardware\victims\firmware\simpleserial-aes
   make

   If this is successful, you'll see an output like the following:

   

   If instead you get an error something like make: *** No rule to make target `simpleserial.elf', needed by `elf'. Stop., this means a required file was missing.

2. Programming the target AVR is accomplished in one of two methods depending on your hardware. The ChipWhisperer Capture Rev 2 uses the external "AVR Studio" program, whereas the CW1173 and CW1200 use a programmer menu from the ChipWhisperer-Capture software. To see details refer to either CW1002_ChipWhisperer_Capture-Rev2#CWCR2:_Using_the_AVR_Programmer or CW1173_ChipWhisperer-Lite#CW-Lite:_Programming_AVR.2FXMEGA_Device.

Python Setup

On Linux, installing Python & all the associated packages is much easier than on Windows. Typically you can install them from a package manager, if you are using Fedora Core or similar, just type:

$ sudo yum install python27 python27-devel python27-libs python-pyside numpy scipy python-configobj pyusb
$ sudo pip install pyqtgraph

On Ubuntu or similar:

$ sudo apt-get install python2.7 python2.7-dev python2.7-libs python-numpy python-scipy python-pyside python-configobj python-setuptools python-pip
$ sudo pip install pyusb
$ sudo pip install pyqtgraph

Getting ChipWhisperer

As in the Windows release, you can download a complete ChipWhisperer software release. Alternatively you can clone the ChipWhisperer repository with git, which is very simple on Linux:

$ git clone git://git.assembla.com/chipwhisperer.git
$ cd chipwhisperer
$ git clone git://git.assembla.com/openadc.git

Be aware that the git code may be broken, although we try not to commit completely untested code to the master branch. Either way once you have the chipwhisperer directory somewhere, do the following from within that directory:

$ cd software
$ sudo python setup.py develop
$ cd ../openadc/controlsw/python
$ sudo python setup.py develop

NB: This assumes the python command links to Python-2.7, and not Python-3.x. You may need to specify either python2.7 or python27 as the command instead of python to force this.

Hardware Drivers

The driver for Linux is built in, however you need to allow your user account to access the peripheral. To do so, you'll have to make a file called /etc/udev/rules.d/99-newae.rules . The contents of this file should be:

# CW-Lite
SUBSYSTEM=="usb", ATTRS{idVendor}=="2b3e", ATTRS{idProduct}=="ace2", MODE="0664", GROUP="plugdev"

# CW-1200
SUBSYSTEM=="usb", ATTRS{idVendor}=="2b3e", ATTRS{idProduct}=="ace3", MODE="0664", GROUP="plugdev"

# CW-305 (Artix Target)
SUBSYSTEM=="usb", ATTRS{idVendor}=="2b3e", ATTRS{idProduct}=="c305", MODE="0664", GROUP="plugdev"

# CW-CR2
SUBSYSTEM=="usb", ATTRS{idVendor}=="04b4", ATTRS{idProduct}=="8613", MODE="0664", GROUP="plugdev"
SUBSYSTEM=="usb", ATTRS{idVendor}=="221a", ATTRS{idProduct}=="0100", MODE="0664", GROUP="plugdev"

Then add your username to the plugdev group:

$ sudo usermod -a -G plugdev YOUR-USERNAME

And reset the udev system:

$ sudo udevadm control --reload-rules

Finally log out & in again for the group change to take effect.

You can always find the latest version of this file in GIT.

FTDI Hardware Driver (SASEBO-W, SAKURA-G, SASEBO-GII)

This is only required for supporting FTDI-connected hardware such as the SASEBO-W, SAKURA-G, SASEBO-GII. This is NOT required for the ChipWhisperer Capture Rev2.

First, you need to install the D2XX drivers & python module. See the section #Optional_Packages.

Currently, there is a bit of a hack needed. You have to create (or modify if it exists) the file /etc/udev/rules.d/99-libftdi.rules . The following modifications will cause any FTDI-serial device to stop working, so backup the existing file! The contents of this file should be:

SUBSYSTEM=="usb", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6010", MODE="0664", GROUP="plugdev"
ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6010", RUN+="/bin/sh -c 'echo $kernel > /sys/bus/usb/drivers/ftdi_sio/unbind'"

Then add your username to the plugdev group (if not already done):

$ sudo usermod -a -G plugdev YOUR-USERNAME

And reset the udev system:

$ sudo udevadm control --reload-rules

Finally log out & in again for the group change to take effect.

Python Setup

1. Ensure your user account has a password. In order for the 'sudo' command to work it requires you to type your password, so if you don't have one enabled be sure to set a temporary password now.

2. Install the 'homebrew' system, see brew.sh for details. Briefly, you can install it by pasting the following in a terminal:

   $ ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

3. Install PySide using homebrew:

   $ brew install pyside

   The install will probably print a message like this:

   

   Note you must run that command in order to successfully import the modules, in this example it would be:

   $ mkdir -p /Users/macmini/Library/Python/2.7/lib/python/site-packages
   $ echo 'import site; site.addsitedir("/usr/local/lib/python2.7/site-packages")' >> /Users/macmini/Library/Python/2.7/lib/python/site-packages/homebrew.pth

Working SciPy Distribution

You may need to upgrade your scipy from the base install, if you wish to do template attacks. This is not needed for other attacks, so please only proceed with the following if you receive an error that your version of scipy is too old.

The easiest method is to use brew again:

brew install scipy

You will also need to follow the instructions as above (inserting the link to the brew site-packages location). You will finally need to run the following:

brew link --overwrite numpy

AVR-GCC Install

You can easily use brew to install avr-gcc, as decribed at OSX-Cross Project:

$ brew tap osx-cross/avr

$ brew install avr-libc