As of August 2020 the site you are on (wiki.newae.com) is deprecated, and content is now at rtfm.newae.com.

Difference between revisions of "Installing ChipWhisperer"

From ChipWhisperer Wiki
Jump to: navigation, search
(5 intermediate revisions by 3 users not shown)
Line 9: Line 9:
 
* '''PyPi Package:''' <code>pip install chipwhisperer</code>. Only includes the software - doesn't come with the hardware source files, drivers, or example firmware.
 
* '''PyPi Package:''' <code>pip install chipwhisperer</code>. Only includes the software - doesn't come with the hardware source files, drivers, or example firmware.
 
* '''Git Repository:''' Get the latest, bleeding-edge features and bugs. Recommended if you're an experienced developer and you want to contribute to ChipWhisperer.
 
* '''Git Repository:''' Get the latest, bleeding-edge features and bugs. Recommended if you're an experienced developer and you want to contribute to ChipWhisperer.
 +
'''NOTE TO USERS WITH AN ARM TARGET:''' To build firmware, you'll need the GNU Embedded Toolchain For ARM. This is included with the VM. Otherwise please see '''Installing ARM Toolchain''' at the bottom of the page.
 +
 
<br>
 
<br>
 
{{Warningbox|If you are installing 64-bit Python rather than 32-bit, and the ChipWhisperer software's graph widget's axis disappear, the fix is this: ''pip uninstall pyside'' and then ''pip install https://download.qt.io/official_releases/pyside/PySide-1.2.2-cp27-none-win_amd64.whl''. This uninstalls the current pyside package and installs the official QT Pyside package.}}
 
{{Warningbox|If you are installing 64-bit Python rather than 32-bit, and the ChipWhisperer software's graph widget's axis disappear, the fix is this: ''pip uninstall pyside'' and then ''pip install https://download.qt.io/official_releases/pyside/PySide-1.2.2-cp27-none-win_amd64.whl''. This uninstalls the current pyside package and installs the official QT Pyside package.}}
  
 +
<br>
 
{{Warningbox|You may need to add ''--trusted-host pypi.python.org'' to the ''pip install'' command to allow HTTP connections. This is done as follows for example: ''sudo pip install --trusted-host pypi.python.org pyusb''}}
 
{{Warningbox|You may need to add ''--trusted-host pypi.python.org'' to the ''pip install'' command to allow HTTP connections. This is done as follows for example: ''sudo pip install --trusted-host pypi.python.org pyusb''}}
  
Line 18: Line 21:
  
 
{{CollapsibleSection
 
{{CollapsibleSection
|intro = = Using VMWare Virtual Machine =
+
|intro = === Using VMWare Virtual Machine ===
 
|content= Installing ChipWhisperer/Using VMWare Virtual Machine}}
 
|content= Installing ChipWhisperer/Using VMWare Virtual Machine}}
  
 
{{CollapsibleSection
 
{{CollapsibleSection
|intro = = Automatic Windows Installer =
+
|intro = === Automatic Windows Installer ===
 
|content= Installing ChipWhisperer/Windows Installer}}
 
|content= Installing ChipWhisperer/Windows Installer}}
  
 
{{CollapsibleSection
 
{{CollapsibleSection
|intro= = Manual Install - Windows =
+
|intro= === Manual Install - Windows ===
 
|content= Installing ChipWhisperer/Required Tools - Windows}}
 
|content= Installing ChipWhisperer/Required Tools - Windows}}
  
 
{{CollapsibleSection
 
{{CollapsibleSection
|intro= = Manual Install - Linux =
+
|intro= === Manual Install - Linux ===
 
|content= Installing ChipWhisperer/Required Tools - Linux}}
 
|content= Installing ChipWhisperer/Required Tools - Linux}}
  
 
{{CollapsibleSection
 
{{CollapsibleSection
|intro= = Manual Install - Mac OS X =
+
|intro= === Manual Install - Mac OS X ===
 
|content= Installing ChipWhisperer/Required Tools - Mac OS X}}
 
|content= Installing ChipWhisperer/Required Tools - Mac OS X}}
  
 
{{CollapsibleSection
 
{{CollapsibleSection
|intro= = Installing ChipWhisperer from Releases =
+
|intro= === Installing ChipWhisperer from Releases ===
 
|content= Installing ChipWhisperer/Installing ChipWhisperer from Releases}}
 
|content= Installing ChipWhisperer/Installing ChipWhisperer from Releases}}
  
 
{{CollapsibleSection
 
{{CollapsibleSection
|intro= = Installing ChipWhisperer from PyPi =
+
|intro= === Installing ChipWhisperer from PyPi ===
 
|content= Installing ChipWhisperer/Installing ChipWhisperer from PyPi}}
 
|content= Installing ChipWhisperer/Installing ChipWhisperer from PyPi}}
  
 
{{CollapsibleSection
 
{{CollapsibleSection
|intro= = Installing ChipWhisperer from Git =
+
|intro= === Installing ChipWhisperer from Git ===
 
|content= Installing ChipWhisperer/Installing ChipWhisperer from Git}}
 
|content= Installing ChipWhisperer/Installing ChipWhisperer from Git}}
  
 
{{CollapsibleSection
 
{{CollapsibleSection
|intro= = Quick Tests =
+
|intro= === Installing ARM Toolchain ===
 +
|content= Installing ChipWhisperer/Installing_ARM_Toolchain}}
 +
 
 +
<!-- {{CollapsibleSection
 +
|intro= === Quick Tests ===
 
|content= Installing ChipWhisperer/Quick Tests}}
 
|content= Installing ChipWhisperer/Quick Tests}}
 +
-->
  
 
[[Category:Introduction]]
 
[[Category:Introduction]]

Revision as of 13:31, 27 September 2018

This page describes how to install the ChipWhisperer software.

There are five ways to set up ChipWhisperer:

  • VMWare Virtual Machine: Get a pre-prepared virtual machine image with all of the required tools already installed. Recommended for beginners.
  • Windows Installer Get a Windows binary that installs the ChipWhisperer repository to your computer. Does not include WinAVR compiler.
  • ChipWhisperer Releases: Get a zip file with the latest stable ChipWhisperer code and run it on your own environment.
  • PyPi Package: pip install chipwhisperer. Only includes the software - doesn't come with the hardware source files, drivers, or example firmware.
  • Git Repository: Get the latest, bleeding-edge features and bugs. Recommended if you're an experienced developer and you want to contribute to ChipWhisperer.

NOTE TO USERS WITH AN ARM TARGET: To build firmware, you'll need the GNU Embedded Toolchain For ARM. This is included with the VM. Otherwise please see Installing ARM Toolchain at the bottom of the page.


If you are installing 64-bit Python rather than 32-bit, and the ChipWhisperer software's graph widget's axis disappear, the fix is this: pip uninstall pyside and then pip install https://download.qt.io/official_releases/pyside/PySide-1.2.2-cp27-none-win_amd64.whl. This uninstalls the current pyside package and installs the official QT Pyside package.


You may need to add --trusted-host pypi.python.org to the pip install command to allow HTTP connections. This is done as follows for example: sudo pip install --trusted-host pypi.python.org pyusb



Using VMWare Virtual Machine

Right-black-arrow.png

If this is your first time using the ChipWhisperer toolchain, the easiest way to start is to use a virtual machine with everything already set up for you.

  1. Install the VMWare Player software (free). Note that this program is available for Windows and Linux - if you're running a Mac, you're out of luck.
  2. Download a ChipWhisperer virtual machine image release. Look for the latest release (4.0.1 as of now).
  3. Unzip the VMWare image and open the file ChipWhisperer xxxxx.vmx in VMWare Player.

Once you've opened this, you may want the latest version of the ChipWhisperer software - the version packaged with the VM image could be quite old. To do this, open LXTerminal in Ubuntu and run the following commands:

cd chipwhisperer
git pull

If you ever want to switch versions, you can run

git checkout <release number>

For example, git checkout 0.11RC will move back to the 0.11 release. git checkout master will always give you the latest software.

The password for the default account cwuser is cwpassword

There's an old Youtube tutorial of this setup available online.

=== Using VMWare Virtual Machine === If this is your first time using the ChipWhisperer toolchain, the easiest way to start is to use a virtual machine with everything already set up for you.

  1. Install the VMWare Player software (free). Note that this program is available for Windows and Linux - if you're running a Mac, you're out of luck.
  2. Download a ChipWhisperer virtual machine image release. Look for the latest release (4.0.1 as of now).
  3. Unzip the VMWare image and open the file ChipWhisperer xxxxx.vmx in VMWare Player.

Once you've opened this, you may want the latest version of the ChipWhisperer software - the version packaged with the VM image could be quite old. To do this, open LXTerminal in Ubuntu and run the following commands:

cd chipwhisperer
git pull

If you ever want to switch versions, you can run

git checkout <release number>

For example, git checkout 0.11RC will move back to the 0.11 release. git checkout master will always give you the latest software.

The password for the default account cwuser is cwpassword

There's an old Youtube tutorial of this setup available online.


Automatic Windows Installer

Right-black-arrow.png

Starting with ChipWhisperer v3.5.1 there is a 32-bit and 64-bit Windows installer. This installer packages together:

  • ChipWhisperer directory (same as in GIT).
  • Python binary & required libraries.
  • Windows USB drivers.
  • GIT too for updates.

This will install ChipWhisperer to a location on your hard drive. Note it must be somewhere you can edit, as you may need to change or rebuild firmware files as part of the tutorials.

=== Automatic Windows Installer === Starting with ChipWhisperer v3.5.1 there is a 32-bit and 64-bit Windows installer. This installer packages together:

  • ChipWhisperer directory (same as in GIT).
  • Python binary & required libraries.
  • Windows USB drivers.
  • GIT too for updates.

This will install ChipWhisperer to a location on your hard drive. Note it must be somewhere you can edit, as you may need to change or rebuild firmware files as part of the tutorials.


Manual Install - Windows

Right-black-arrow.png

Python

For any of the other installation methods, you'll need to have Python 2 installed on your computer. If you already a recent version of Python installed (2.7.x), you can skip this step. Note that Python 3.x will not work with this codebase. There's also a bit of setup that's needed to get other tools and prepare other drivers.

The recommend method of installing Python is to use a distribution called WinPython. This setup avoids installing Python globally, and includes most of the software you will need. In addition it makes it possible to install 32-bit and 64-bit Python on the same system with minimal problems. This can be very useful as the 64-bit version is handy for doing analysis on large data sets.

To install WinPython 2.7.x, Download a release in the 2.7.x branch from the WinPython site. It's recommended to use the 32-bit version, but you can also use the 64-bit version. Also, note that the recent releases (like WinPython-32bit-2.7.13.0Zero) don't come with any pre-installed packages. We recommend WinPython 2.7.10.3.

Note that certain drivers (such as the SmartCard driver) do not work on the 64-bit version. Choose a reasonable location to install this to - note the default is simply in the download directory. Instead it's recommended to find a directory such as c:\WinPython32bit-2.7.10.3, or into your local directory such as c:\Users\yourname\WinPython-32bit-2.7.10.3.

Go to your installation directory for WinPython, and run the shortcut called WinPython Command Prompt.exe. This will give you a command prompt which is setup to run Python along with associated scripts.

Optional: You can add the python.exe you just installed to your PATH. To do so navigate to your installation folder, and run the WinPython Control Panel.exe program. Then select Advanced -> Register distribution.... If you do not do this, you will have to run all commands in this document via the WinPython Command Prompt.exe. If you plan on running both 32-bit and 64-bit Python, you should not register them. Instead explicitly call the correct Python by always running the WinPython Command Prompt.exe, and then calling specific programs (such as CW Capture or Analyzer) from that command prompt.

Python Packages

There are a number of packages that the ChipWhisperer project uses. You'll need to install these so that the software can run. Note that the PyPi install process should automatically install these, so you shouldn't need to manually install everything there.

Run the following commands to get the needed packages:

  • PyQTGraph: pip install pyqtgraph
  • ConfigObj: pip install configobj

You might also need some extra packages. Generally you can avoid them unless you have specific need of the features they enable:

PyUSB: if you're planning to use the ChipWhisperer Capture Rev2 hardware, this is necessary. You can install this using pip:

  • pip install pyusb
  • If that fails, try specifying the latest version, like: pip install pyusb==1.0.0b1

FTD2XX: ftd2xx is required for SASEBO-W, SAKURA-G, and SASEBO-GII Support. To install this package, download a copy of the ftd2xx repository and unzip it somewhere. Then run the following where you unzipped it:

python setup.py install

This package will also require you to install the FTDI D2XX Drivers. In the preceeding link simply find the correct driver for your OS Version and install that.

MYSQL: If you want to use the MySQL trace format (not used by default), you'll need to install umysql:

pip install umysql

PYSCARD: If planning on using a PS/SC smartcard reader (i.e. standard USB-connected reader), you will need to install pyscard.

Installing Hardware Drivers

Details of driver installation are on specific pages for supported hardware (such as cwcapturerev2 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 avr-gcc on Windows (if using the Virtual Machine, the following is not required, as the VM comes setup with the AVR compiler already). On Windows, you could choose to install:

To test the code build, follow these steps:

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:

image

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.

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.

For details about programming the targets, see Tutorial B1 Building a SimpleSerial Project.

WinAVR Path Settings

By default, WinAVR is added to your system path. This means you can run avr-gcc, make and other programs from your normal Windows command line. You may not want this on certain systems where you already have similar tools installed. In which case either uncheck the Add WinAVR to Path option, or edit your system path to remove the WinAVR directories.

If you do not add it to the system path, you’ll need a method of readding the WinAVR directories when you want to use WinAVR. To do so create a file called winavr.bat in C:\WinAVR-20100110 with the following contents:

set PATH=%PATH%;C:\WinAVR-20100110\bin;C:\WinAVR-20100110\utils\bin
cmd

Now when you want to run WinAVR (e.g. to continue the examples here), you can simply double-click on the winavr.bat file. This will configure the path for just that terminal, rather than every terminal you open.

Note if using WinAVR on Windows 8.1/10, you must replace the dll msys-1.0.dll with an updated version. See Windows 8.1 Fix for a link to this DLL replacement.

=== Manual Install - Windows ===

Python

For any of the other installation methods, you'll need to have Python 2 installed on your computer. If you already a recent version of Python installed (2.7.x), you can skip this step. Note that Python 3.x will not work with this codebase. There's also a bit of setup that's needed to get other tools and prepare other drivers.

The recommend method of installing Python is to use a distribution called WinPython. This setup avoids installing Python globally, and includes most of the software you will need. In addition it makes it possible to install 32-bit and 64-bit Python on the same system with minimal problems. This can be very useful as the 64-bit version is handy for doing analysis on large data sets.

To install WinPython 2.7.x, Download a release in the 2.7.x branch from the WinPython site. It's recommended to use the 32-bit version, but you can also use the 64-bit version. Also, note that the recent releases (like WinPython-32bit-2.7.13.0Zero) don't come with any pre-installed packages. We recommend WinPython 2.7.10.3.

Note that certain drivers (such as the SmartCard driver) do not work on the 64-bit version. Choose a reasonable location to install this to - note the default is simply in the download directory. Instead it's recommended to find a directory such as c:\WinPython32bit-2.7.10.3, or into your local directory such as c:\Users\yourname\WinPython-32bit-2.7.10.3.

Go to your installation directory for WinPython, and run the shortcut called WinPython Command Prompt.exe. This will give you a command prompt which is setup to run Python along with associated scripts.

Optional: You can add the python.exe you just installed to your PATH. To do so navigate to your installation folder, and run the WinPython Control Panel.exe program. Then select Advanced -> Register distribution.... If you do not do this, you will have to run all commands in this document via the WinPython Command Prompt.exe. If you plan on running both 32-bit and 64-bit Python, you should not register them. Instead explicitly call the correct Python by always running the WinPython Command Prompt.exe, and then calling specific programs (such as CW Capture or Analyzer) from that command prompt.

Python Packages

There are a number of packages that the ChipWhisperer project uses. You'll need to install these so that the software can run. Note that the PyPi install process should automatically install these, so you shouldn't need to manually install everything there.

Run the following commands to get the needed packages:

  • PyQTGraph: pip install pyqtgraph
  • ConfigObj: pip install configobj

You might also need some extra packages. Generally you can avoid them unless you have specific need of the features they enable:

PyUSB: if you're planning to use the ChipWhisperer Capture Rev2 hardware, this is necessary. You can install this using pip:

  • pip install pyusb
  • If that fails, try specifying the latest version, like: pip install pyusb==1.0.0b1

FTD2XX: ftd2xx is required for SASEBO-W, SAKURA-G, and SASEBO-GII Support. To install this package, download a copy of the ftd2xx repository and unzip it somewhere. Then run the following where you unzipped it:

python setup.py install

This package will also require you to install the FTDI D2XX Drivers. In the preceeding link simply find the correct driver for your OS Version and install that.

MYSQL: If you want to use the MySQL trace format (not used by default), you'll need to install umysql:

pip install umysql

PYSCARD: If planning on using a PS/SC smartcard reader (i.e. standard USB-connected reader), you will need to install pyscard.

Installing Hardware Drivers

Details of driver installation are on specific pages for supported hardware (such as cwcapturerev2 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 avr-gcc on Windows (if using the Virtual Machine, the following is not required, as the VM comes setup with the AVR compiler already). On Windows, you could choose to install:

To test the code build, follow these steps:

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:

image

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.

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.

For details about programming the targets, see Tutorial B1 Building a SimpleSerial Project.

WinAVR Path Settings

By default, WinAVR is added to your system path. This means you can run avr-gcc, make and other programs from your normal Windows command line. You may not want this on certain systems where you already have similar tools installed. In which case either uncheck the Add WinAVR to Path option, or edit your system path to remove the WinAVR directories.

If you do not add it to the system path, you’ll need a method of readding the WinAVR directories when you want to use WinAVR. To do so create a file called winavr.bat in C:\WinAVR-20100110 with the following contents:

set PATH=%PATH%;C:\WinAVR-20100110\bin;C:\WinAVR-20100110\utils\bin
cmd

Now when you want to run WinAVR (e.g. to continue the examples here), you can simply double-click on the winavr.bat file. This will configure the path for just that terminal, rather than every terminal you open.

Note if using WinAVR on Windows 8.1/10, you must replace the dll msys-1.0.dll with an updated version. See Windows 8.1 Fix for a link to this DLL replacement.


Manual Install - Linux

Right-black-arrow.png

Python

On Linux, installing Python & all the associated packages is straightforward. 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 the AVR Toolchain

Many of the tutorials use the AVR XMEGA microcontrollers as a target. In order to compile code for these targets, you'll need the AVR toolchain. This is easy to set up:

sudo apt-get install avr-libc gcc-avr

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.

=== Manual Install - Linux ===

Python

On Linux, installing Python & all the associated packages is straightforward. 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 the AVR Toolchain

Many of the tutorials use the AVR XMEGA microcontrollers as a target. In order to compile code for these targets, you'll need the AVR toolchain. This is easy to set up:

sudo apt-get install avr-libc gcc-avr

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.


Manual Install - Mac OS X

Right-black-arrow.png

Python

The following have been tested on Mac OS X Yosemite (10.10) - earlier versions may not have a recent enough Python installation (recommended 2.7.6 or later). It's possible to install other Python versions on your Mac OS X via the 'homebrew' system, we will use this for installing a few additional required tools.

  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. As PySide is based on Qt 4, which is not officially supported by Homebrew, you will need to load the homebrew-qt4 tap:

    $ brew tap cartr/qt4
  4. Install PySide using homebrew:

    $ brew install pyside

    If you recieve an error saying that no such package exists, you can also install PySide using the pip installer

    pip install -U PySide

    The install will probably print a message like this:

    image

    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

SciPy

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

libusb

libusb is needed for the ChipWhisperer software to communicate with the board.

Again, use brew:

brew install libusb

AVR-GCC

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

$ brew tap osx-cross/avr

$ brew install avr-gcc
=== Manual Install - Mac OS X ===

Python

The following have been tested on Mac OS X Yosemite (10.10) - earlier versions may not have a recent enough Python installation (recommended 2.7.6 or later). It's possible to install other Python versions on your Mac OS X via the 'homebrew' system, we will use this for installing a few additional required tools.

  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. As PySide is based on Qt 4, which is not officially supported by Homebrew, you will need to load the homebrew-qt4 tap:

    $ brew tap cartr/qt4
  4. Install PySide using homebrew:

    $ brew install pyside

    If you recieve an error saying that no such package exists, you can also install PySide using the pip installer

    pip install -U PySide

    The install will probably print a message like this:

    image

    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

SciPy

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

libusb

libusb is needed for the ChipWhisperer software to communicate with the board.

Again, use brew:

brew install libusb

AVR-GCC

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

$ brew tap osx-cross/avr

$ brew install avr-gcc


Installing ChipWhisperer from Releases

Right-black-arrow.png

Once you have a working Python installation, you're ready to install and run ChipWhisperer.

First, download a ChipWhisperer release. You can get these from the Releases page. Generally, the latest release is a good choice, but you might need an older version for various reasons. You want the source code in .zip or .tar.gz format - not a VMWare image.

Next, uncompress your downloaded source code somewhere. Generally, 'somewhere' will become your ChipWhisperer working directory. For example, on Windows, you might want to use C:\chipwhisperer\.

Once you've got the file, run the Python install procedure (setup.py). Use the develop command to indicate that the files will probably be changing frequently. to do this, open a terminal and run the following, adjusting paths as needed:

cd c:\chipwhisperer\software
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.

In Linux, you might need to run this as root: sudo python setup.py develop

The installation is now finished. 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, 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:

Youtube-win7-install.png

=== Installing ChipWhisperer from Releases === Once you have a working Python installation, you're ready to install and run ChipWhisperer.

First, download a ChipWhisperer release. You can get these from the Releases page. Generally, the latest release is a good choice, but you might need an older version for various reasons. You want the source code in .zip or .tar.gz format - not a VMWare image.

Next, uncompress your downloaded source code somewhere. Generally, 'somewhere' will become your ChipWhisperer working directory. For example, on Windows, you might want to use C:\chipwhisperer\.

Once you've got the file, run the Python install procedure (setup.py). Use the develop command to indicate that the files will probably be changing frequently. to do this, open a terminal and run the following, adjusting paths as needed:

cd c:\chipwhisperer\software
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.

In Linux, you might need to run this as root: sudo python setup.py develop

The installation is now finished. 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, 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:

Youtube-win7-install.png


Installing ChipWhisperer from PyPi

Right-black-arrow.png

An alternative install method is to get ChipWhisperer directly from the Python Package Index. To do this, run the command

pip install chipwhisperer

Note that this package doesn't include anything except the software. The hardware pieces (including schematics, gerbers, and firmware for victims/scopes) isn't included here. However, if you need a couple of the utilities from the software, this is a quick and lightweight way to install them.

=== Installing ChipWhisperer from PyPi === An alternative install method is to get ChipWhisperer directly from the Python Package Index. To do this, run the command

pip install chipwhisperer

Note that this package doesn't include anything except the software. The hardware pieces (including schematics, gerbers, and firmware for victims/scopes) isn't included here. However, if you need a couple of the utilities from the software, this is a quick and lightweight way to install them.


Installing ChipWhisperer from Git

Right-black-arrow.png

If you want the cutting-edge version of ChipWhisperer, you can clone the repository. If you have Git already set up, this is easy to do:

git clone https://github.com/newaetech/chipwhisperer.git
cd chipwhisperer
git checkout develop
cd software
python setup.py develop --user

The user flag installs ChipWhisperer in the user's local python site-packages directory. Note bleeding-edge development is done on the "develop" branch, which you probably want if you are trying GIT.

You may also want the OpenADC software, which is necessary to build new firmware for the ChipWhisperer FPGA. This is unnecessary for most users. If you need it:

cd ..
git submodule init
git submodule update
cd openadc/controlsw/python
python setup.py develop --user

=== Installing ChipWhisperer from Git === If you want the cutting-edge version of ChipWhisperer, you can clone the repository. If you have Git already set up, this is easy to do:

git clone https://github.com/newaetech/chipwhisperer.git
cd chipwhisperer
git checkout develop
cd software
python setup.py develop --user

The user flag installs ChipWhisperer in the user's local python site-packages directory. Note bleeding-edge development is done on the "develop" branch, which you probably want if you are trying GIT.

You may also want the OpenADC software, which is necessary to build new firmware for the ChipWhisperer FPGA. This is unnecessary for most users. If you need it:

cd ..
git submodule init
git submodule update
cd openadc/controlsw/python
python setup.py develop --user


Installing ARM Toolchain

Right-black-arrow.png

Installation

Some versions of the Arm GCC compiler appear to produce firmware that do not work. Known working versions include Windows/2018-q2 and Linux/5.4.1 20160919. Versions known not to work include Windows/2018-q1, Windows/2018-q4

To be able to build firmware for ARM Targets, you'll need to install the GNU Toolchain for ARM Devices. An installer for Windows and archives for Linux/Windows can be found here. If you use the installer, make sure the "Add path to environment variable", "Add registry information", and "Launch gccvar.bat" boxes are ticked.

If you're using a Linux based operating system (like the VM), you can install the toolchain via your package manager. For example, in the VM run sudo apt-get install gcc-arm-none-eabi in a terminal.

Once you've done this, open a terminal and type arm-none-eabi-gcc. If this fails, you'll need to add the toolchain to your path.

Installing ARM Toolchain === === Installation

Some versions of the Arm GCC compiler appear to produce firmware that do not work. Known working versions include Windows/2018-q2 and Linux/5.4.1 20160919. Versions known not to work include Windows/2018-q1, Windows/2018-q4

To be able to build firmware for ARM Targets, you'll need to install the GNU Toolchain for ARM Devices. An installer for Windows and archives for Linux/Windows can be found here. If you use the installer, make sure the "Add path to environment variable", "Add registry information", and "Launch gccvar.bat" boxes are ticked.

If you're using a Linux based operating system (like the VM), you can install the toolchain via your package manager. For example, in the VM run sudo apt-get install gcc-arm-none-eabi in a terminal.

Once you've done this, open a terminal and type arm-none-eabi-gcc. If this fails, you'll need to add the toolchain to your path.