4.2. CW1173: ChipWhisperer-Lite Board

The ChipWhisperer-Lite Bare Board consists of two main parts: a multi-purpose power analysis capture instrument, and a target board. The target board is a standard microcontroller which you can implement algorithms onto. For example if you wish to evaluate an AES library, you can program that library into the target board and perform the power analysis.

_images/cwlite_basic.png

4.2.1. Quick-Start Guide

You can see a Video of the quickstart guide, which will take you through all the setup items discussed here:

YouTubeCW1173Demo

4.2.1.1. Connection Quick-Start

  1. Install Python and Dependancies

    Windows:
    • Install Python distribution (such as WinPython), see Installing Python via WinPython

    • Using the Python Command Prompt, use pip to install the following:

      pip install pyside
      pip install configobj
      pip install pyusb
      pip install pyqtgraph
      

    What is included in releases varies. If you get a message saying it is already installed you can simply continue with this tutorial.

    Linux:
    • Python should come pre-installed. If so you’ll also need to install the following from your package manager:

      • pyside
      • configobj
      • scipy
      • numpy

      For example the following shows the install command for Ubuntu:

      sudo apt-get install python2.7 python2.7-dev python2.7-libs python-numpy python-scipy python-pyside python-configobj python-setuptools python-pip
      
    • Some packages may require installation via ‘pip’, as they are not always in your package manager repo:

      $pip install pyusb
      $pip install pyqtgraph
      
    Mac OS-X:
    • Install homebrew, pyside, libusb, along with required Python modules.
    • See MAC OS X for full details.
  2. Download and install ChipWhisperer

    • Download the latest release linked from ChipWhisperer.com

    • Unzip the file somewhere. Generally ‘somewhere’ will become your ChipWhisperer working directory. These examples assume you’ve chosen C:\chipwhisperer as your working directory.

    • Open a Python terminal (again if using WinPython be sure to run the specific Python command prompt), and run the following, adjusting paths as needed to refelct your working directory:

      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\analyzer
    python ChipWhispererAnalyzer.py
    
  1. Connect ChipWhisperer-Lite, install USB Drivers:

    Windows:
    • Plug micro-USB cable into ChipWhisperer-Lite
    • If the “New Hardware Found” wizard doesn’t prompt you for drivers, go to the control panel and find the “ChipWhisperer-Lite” device, and select “Update Drivers”.
    • You can find drivers in c:\chipwhisperer\hardware\capture\chipwhisperer-lite\. You will likely need to extract them from the cwlite_usb_driver.zip file. If so simply extract them somewhere (i.e. your desktop), and then point the new hardware found wizard to that location.
    Linux:
    • Driver installation is not required, but if you do not update the ‘udev’ system, you will be unable to run ChipWhisperer-Capture as a regular user. To update the udev system, first make sure the ChipWhisperer-Lite is Make a file called /etc/udev/rules.d/99-cwlite.rules . The contents of this file should be:

      # allow users to claim the device
      SUBSYSTEM=="usb", ATTRS{idVendor}=="2b3e", ATTRS{idProduct}=="ace2", MODE="0664", GROUP="plugdev"
      
    • 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.

    • Connect the micro-USB cable

    MAC:
    • No special installation required - must ensure you have installed libusb via homebrew (see instructions at MAC OS X).
  2. Run ChipWhisperer-Capture. This can be done from one of three ways:

    • Double-click on CWCapture.pyw in the chipwhisperer\software folder. You must have installed Python into your path for this to work.
    • run python CWCapture.pyw from the chipwhisperer\software folder using a command prompt with Python in the path.
    • run python ChipWhispererCapture.py from the chipwhisperer\software\chipwhisperer\capture directory.

    The last option is the most reliable, in that it should always work on all platforms. If it doesn’t start look for possible missing modules or other useful errors.

    Hint

    The first time you run ChipWhisperer-Capture or -Analyzer, the default setup of the screen is somewhat insane. You can drag windows around or close them to make it look more like the demos here. See the Video quickstart guide as well for details of that.

  3. From the “Scripts” directory, run the ChipWhisperer-Lite: AES SimpleSerial on XMEGA script:

    _images/cwlite_simpleserial.png

    This should connect to the ChipWhisperer-Lite, program the FPGA, and run a few captures. Your screen should look something like this now:

    _images/cwdemo_normal.png
  4. If the previous step fails, you may need to set the path for the “firmware”. This is done by going to the “Tools” menu and selecting the “Config CW Firmware” option. Note on MAC OS X a special command is required instead sometimes, see MAC OS X.

    From there, hit the “FIND” button beside the “FPGA .zip (Release)” option. Point it to the file located at chipwhisperer/hardware/capture/chipwhisperer-lite/cwlite_firmware.zip on your filesystem.

  5. Your ChipWhisperer-Lite is now connected. See the next section for details of the demo attack.

4.2.1.2. Capture and Attack Quickstart

  1. See Tutorial #B5: Breaking AES (Straightforward) for details. Note the hardware setup is slightly different – but you can skip to step 5.5.3, and should be able to pick up from there. Be sure to use the ChipWhisperer-Lite: AES SimpleSerial on XMEGA script instead of the one referenced in step 5.5.3.

4.2.1.3. Important Bugs/Caveats

The following includes various things that might trip you up:

  1. If you save the project before running the capture, you can specify any directory. Traces will be copied to the appropriate location during capture.
  2. If you save the project after running the capture, you must save the project to the same directory that “default-data-dir” exists in. This is normally the folder from where you invoked the Python GUI.
  3. There are a few warnings/exceptions that come up (i.e. divide-by-zero). Generally just keep going and see if things are still working. A number of those are on the TODO list to fix but I didn’t get around to it yet.
  4. The “Total Ops” window which checks for proper AES operation requires PyCrypto to be installed.
  5. By default the XMEGA device was programmed with a partial AES implementation only. This is done to avoid any crypto export issues. This does not affect your side-channel analysis, but be aware the returned value might not appear to be correct (since only the first couple rounds of AES occurred).

4.2.2. Basic Usage Instructions

4.2.2.1. CW-Lite: Programming AVR/XMEGA Device

The CW1173 has built-in support for programming either Atmel AVR or Atmel XMEGA device. This is designed to allow you to program our target boards (either the built-in XMEGA target, or the Multi-Target board).

Note this programmer is fairly simple, and does not provide all the features of a stand-alone programmer.

4.2.2.1.1. AVR Programmer

The AVR device programmer requires four connections to the target: RESET, MOSI, MISO, SCK. See 20-Pin Connector for details of AVR programming pin connections.

4.2.2.1.1.1. Accessing the Programming

To access the AVR Programmer, select the “CW-Lite AVR Programmer” from the pull-down Tools menu:

_images/avrprog_menu.png

Which should give you the AVR Programmer Window.

4.2.2.1.1.2. Clock Source Selection

Note to use the AVR programmer you may require a valid clock source for the AVR. It is suggested to select one of the setup scripts (such as ChipWhisperer-Lite: AES Simple-Serial on ATMega328P) which will generate a 7.37 MHz clock.

Check if the device is found by pressing the “Check Signature” button. The status window will show the detected device based on the signature.

_images/avrprog_sigok.png

If this fails, double-check connections, and ensure the clock source to the AVR is suitable. Note some errors will appear as part of the main window log:

_images/avrprog_fail.png

The default SPI data rate for the programmer is too fast for devices which are running slower than 2 MHz. If programming a device with a clock source slower than 2 MHz, you will need to enable the “Slow Clock Mode”. In “Slow Clock Mode” the entire SAM3U and FPGA clock is changed from 96 MHz to 12 MHz. Note the default fuse bytes for a virgin ATMega328P result in a 1 MHz clock, so you will need to use “slow clock mode” to program the correct fuse bytes, after which point you will not need to use “slow clock mode”.

Note

The ‘slow clock mode’ is used to provide a slower SPI clock than would otherwise be possible. When switching into ‘slow clock mode’ it will cause all DCM blocks in the FPGA to become unlocked. You will need to reset the DCM blocks, or simply restart the CW-Capture software and run the setup script.

4.2.2.1.1.3. Programming the Fuses

By default the AVR programmer allows you to modify the LOW fuse byte only, as this byte controls the clock source selection. To change the value of the fuse byte:

  1. Press the “Read Fuses” button, and the values should be populated
  2. Specify the new low fuse value
  3. Hit “Write Fuses”

See an Online Fuse Calculator to better understand what the values mean.

Tip

If programming a virgin ATMega328P device, the default low-fuse value of 62 results in the internal 8 MHz oscillator being divided down to 1 MHz. Any external clock is ignored.

The low fuse byte must be changed to D0 to use the external clock provided by the ChipWhisperer toolchain.

4.2.2.1.1.4. Programming the Flash

Programming the flash is accomplished by selecting the new .hex file in the “Find” menu, and pressing the “Erase/Program/Verify FLASH” button. The “Status” line will show the following information:

  • File programmed into device
  • Time file was last modified (very useful to confirm you are using changed file when doing development)
  • Status of verification, and number of bytes programmed/verified
_images/avrprog_progok.png

4.2.2.1.2. XMEGA Programmer

The XMEGA device programmer requires only two connections to the target: clock (PDIC) and data (PDID). The PDIC line is usually shared with the RESET pin, and the PDID pin is a specific pin on the XMEGA device. See 20-Pin Connector for details of XMEGA programming pin connections.

_images/xmegaprog_main.png

4.2.2.2. Using Glitch Port

The “GLITCH” port is used for voltage glitching. It’s connected to two MOSFET elements, as the following figure shows:

_images/glitch_lp_hp.png

The CW1173 glitch output can be commanded to turn on either of those MOSFETs via the “Glitch Out Enable” checkboxes:

_images/glitch_gui.png

Be careful using this feature, as you don’t want to short the MOSFETs for too long. It’s also possible to damage the ChipWhisperer-Lite by burning these MOSFETs up if used incorrectly. See tutorial #A3 for more information on using this feature.

4.2.2.3. Using Measure Port

The “MEASURE” port is the input to the low-noise amplifier and ADC.

4.2.2.4. 20-Pin Connector

The pinout is as follows:

Number Name Dir Description
1 +VUSB (5V) O Not Connected on ChipWhisperer-Lite.
2 GND O System GND.
3 +3.3V O +3.3V to Target Device, can be turned off, 200mA available.
4 FPGA-HS1 I/O High Speed Input (normally clock in).
5 PROG-RESET I/O Target RESET Pin (AVR Programmer).
6 FPGA-HS2 I/O High Speed Output (normally clock or glitch out).
7 PROG-MISO I/O SPI input: MISO (for SPI + AVR Programmer).
8 VTarget I Drive this pin with desired I/O voltage in range 1.5V-5V.
9 PROG-MOSI I/O SPI output: MOSI (for SPI + AVR Programmer).
10 FPGA-TARG1 I/O TargetIO Pin 1 - Usually UART TX or RX.
11 PROG-SCK I/O SPI output: SCK (for SPI + AVR Programmer).
12 FPGA-TARG2 I/O TargetIO Pin 2 - Usually UART RX or TX.
13 PROG-PDIC I/O PDI Programming Clock (XMEGA Programmer), or CS pin (SPI).
14 FPGA-TARG3 I/O TargetIO Pin 3 - Usually bidirectional IO for smartcard.
15 PROG-PDID I/O PDI Programming Data (XMEGA Programmer).
16 FPGA-TARG4 I/O TargetIO Pin 4 - Usually trigger input.
17 GND O  
18 +3.3V O  
19 GND O  
20 +VUSB (5V) O Not Connected on ChipWhisperer-Lite.

4.2.2.5. 8-Pin SmartCard Connector

The CW1173 contains two 8-pin connectors, which use our standard 8-pin Smart-Card header pinout. One header connects to the SAM3U device (which has ISO-7816 drivers), one header connects to the FPGA. Note there is currently no firmware support for these devices, but the hardware is designed for any of the following:

  • Emulating a smart card (use interposer board), or fuzzing a smart card reader
  • Communicating to a smart card
  • Sniffing traffic between a legitimate reader and smart card
  • Side-channel analysis of smart card device

Header J7 (Connects to SAM3U):

Number Name Dir Description
1 VCCIO O 3.3V Supply (from linear regulator, always on)
2 GND O System GND
3 RST I/O Reset (SAM3U: PA3)
4 PRESENT I Used to detect presence of smart card (SAM3U: PA2)
5 CLK I/O Clock (SAM3U: PA25, ‘CLK2’. FPGA: P131)
6 I/O I/O I/O Line (SAM3U: PA22), 10k pull-up
7 AUX1 I/O Spare line (SAM3U: PA4)
8 AUX2 I/O Spare line (SAM3U: PA5)

Header J6 (Connects to FPGA):

Number Name Dir Description
1 VCCIO O 3.3V Supply (from FPGA supply)
2 GND O System GND
3 RST I/O Reset (FPGA: P102)
4 PRESENT/VPP I Not Connected (mount R60 to connect to P101)
5 CLK I/O Clock (FPGA: P100)
6 I/O I/O I/O Line (FPGA: P99), 10k pull-up
7 AUX1 I/O Spare line (FPGA: P98)
8 AUX2 I/O Spare line (FPGA: P97)

4.2.2.6. Upgrading SAM3U Firmware

When talking about the ChipWhisperer-Lite’s firmware, there is really two parts to this:

  1. The FPGA Bitstream file.
  2. The SAM3U USB interface chip firmware.

The FPGA bitstream alone is what is normally configured by the ChipWhisperer-Capture software. This bitstream is always the most up-to-date, since it’s automatically reloaded by the computer every time you power cycle the ChipWhisperer-Capture. The SAM3U firmware however is not automatically updated, but it tends to change less frequently.

4.2.2.6.1. Checking Firmware Version

The firmware version is printed at start-up. You will see a line that looks like this indicating the version of the SAM3U Firmware:

Found CW-Lite, Serial Number = 442031204630xxxxxxxxxxx
SAM3U Firmware version = 0.11 b0
Programmed FPGA

If your firmware version is outdated, a warning will be printed. You can also see the firmware version in the Config CW Firmware dialog:

_images/sam3fwver.png

Note the main version is 0.11 in this example. The “b0” indicates a “build” number. Typically this will be “build 0”, but special versions will use a different build number to indicate a variant of a regular version.

4.2.2.6.2. Entering Bootloader Mode

Before updating, you must put your ChipWhisperer-Lite into bootloader mode. Once put into this mode you will need to load a new firmware file. The two methods of doing this are:

  1. Using ChipWhisperer-Capture GUI

    1. Connect to the ChipWhisperer-Lite.
    2. From the Tools menu select Config CW Firmware.
    3. Select the Open SAM3U Update Widget button.
    4. Press the Enable Bootloader Mode button.
    5. The blue LED will stop flashing, and the device will reconnect in programmer mode (see below).
  2. If this method doesn’t work, you can use the manual override method. To use a metal object:

    1. Short the jumper labeled “ERASE” on the ChipWhisperer-Lite. Do this while the device is connected via micro-USB. The blue LED should stop flashing at this point, and will stay either on or off (depending when you shorted the jumper). This can be accomplished by anything metallic - for example using a screwdriver or tweezers:

      _images/short_screwdriver.jpg _images/short_tweezers.jpg
    2. Unplug and Replug the micro-USB port.

Once you are in bootloader mode, both the blue and red LED will be very dimmly lit:

_images/lights_prog.jpg

This indicates it is in bootloader mode. The device will now attach as a serial port. If you are using Windows this may take a few minutes to happen.

If using Linux, you can use dmesg to verify the serial port was connected OK.

4.2.2.6.3. Upgrading with BOSSA

BOSSA is a programming tool for the Atmel SAM devices. The ChipWhisperer-Capture software can call the command-line tool for you. To do this:

  1. Open the SAM3U Firmware Loader - if you just used it to enter bootloader mode, you will already have this window open. If not:

    1. Start ChipWhisperer-Capture.
    2. Select the “ChipWhisperer/OpenADC” and “ChipWhisperer-Lite” target, but do not click connect (as it won’t work).
    3. From the Tools menu select Config CW Firmware.
    4. Press the Open SAM3U Update Widget button.
  2. Hopefully the bossac binary was found. ChipWhisperer-Capture has a binary for Windows and Linux already present, which should be located at chipwhisperer/capture/hardware/chipwhisperer-lite/bossa. If these binaries are not working, see the BOSSA homepage to download an appropriate installer for your system.

    Once ready, point to the bossac binary for your system.

  3. The firmware update file is normally located in hardware/capture/chipwhisperer-lite/sam3u_fw/SAM3U_VendorExample/Debug/SAM3U_CW1173.bin. If not found, again point your system to this. If the window is setup correctly, it should look like this:

    _images/bossa_gui.png
  4. Hit the Run bossac button. You should see a decleration of success printed in the output.

  5. Unplug and replug the ChipWhisperer-Lite. The blue LED should be blinking again. Close ChipWhisperer-Capture and re-open it to attempt a re-connect.

If things don’t work, you can manually run bossac as follows:

bossac -e -w -v -b /path/to/SAM3U_CW1173.bin

If you are on Linux, you may need to either fix permissions on the serial port, or run bossac as root/sudo. See below for details.

4.2.2.6.3.1. Linux-Specific Instructions

You may need to give yourself write permission for the serial port. This can be done on some systems easily by adding yourself to the dialout user group. For example, assuming your username was cwuser:

  1. $ sudo usermod -a -G dialout cwuser
  2. Log out and log back in again for changes to take effect.

You may also need to build bossac from sources, as the provided binary does not work with your system. Details of how to perform this are provided next:

To build BOSSA, it is recommended to use our simplified bossac repository, which only builds the command-line version. To build this perform these steps:

  1. Download a copy of the GIT repo, or clone with git clone git@github.com:newaetech/BOSSA.git (see github.com/newaetech/bossa for the full repo).
  2. Unzip the directory if you downloaded the zip.
  3. Run make.
  4. The binary should be in bin\bossac.

4.2.2.7. Breaking Target Section Apart

You may wish to break the target section apart from the main capture board. This can easily be accomplished by following these instructions:

  1. Using a sharp knife (such as Xacto knife or retractable safety knife), cut the traces on the bottom side of the board along the cut line. Pass the knife back and forth several times. Scoring the board deeply will make the breaking process easier and less stressful on the PCB:

    _images/breakstep1.png
  2. Score the board on the top side:

_images/breakstep2.png
  1. Select a surface to break the board over. It is suggested to have a piece of cardboard or boxboard down to protect components on the bottom side of the ChipWhisperer:
_images/breakstep3.png
  1. Hold the main board section flat, apply even pressure to the target board section. It should snap downward:
_images/breakstep4.png
  1. Separate the two sections:
_images/breakstep5.png

You can see a Video of the process here:

YouTubeCW1173Break

Applying even pressure will help prevent damage to the ChipWhisperer-Lite main section. Flexing the PCB too much may cause damage to solder joints, but by holding the entire board flat against the edge this is prevented.

4.2.3. Advanced Usage

4.2.3.1. Mounting Jumpers

Note the ChipWhisperer-Lite main board and target section contain a number of jumper options. By default these are not mounted, and solder jumper bridges on the PCB have been bridged to select the appropriate options when required. Some options are only solder jumpers, which to move the jumper requires a soldering iron to bridge or clear the appropriate connections.

The following lists jumpers on the ChipWhisperer-Lite / Target Section:

Capture Section Jumpers:
  • JP4 is the “RESET” net for the SAM3U processor.
  • JP2 causes the SAM3U processor flash memory to be erased. When the chip is erased a rom-resident bootloader takes over. See section XXXXX for bootloader details.
  • JP5 selects the IO voltage for the FPGA bank which connects to the 20-pin target. By default SJ6 selects this to be 3.3V. It is not recommended to change this, as it is easy to damage the FPGA by feeding an out-of-range voltage in.
  • SJ1 selects if the power supply comes from the Micro-USB connector (default) or an external 5V supply at the +5VIN pin.
Target Section Jumpers:
  • JP7 connects the “MEASURE” SMA to the XMEGA VCC Rail. Shorted by default with SJ4.
  • JP6 connects the “GLITCH” SMA to the XMEGA VCC Rail. Shorted by default with SJ5.
  • JP12 can be used to feed an external voltage into the XMEGA VCC Rail. By default SJ3 connects this to 3.3V.
  • SJ2 selects if the 3.3V rail comes from the 20-pin IDC connector (i.e. ChipWhisperer-Lite board), or via an optional LDO and USB connector.