Installation

You get your choice of installing ChipWhisperer and its prerequisites: the easy way or the hard way.

Basic
Advanced

Virtual Machine (VirtualBox)

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. Note that Linux users may find it easier to do a manual install ( GNU/Linux):

  • Install VirtualBox. This program is freely available on Windows, Mac, and Linux.

  • Install the VirtualBox Extension pack, which can be found on the VirtualBox downloads page linked above. This is necessary for the VM to interact with the ChipWhisperer hardware.

  • Download a ChipWhisperer virtual machine image release or build it yourself using Vagrant. VM images come as .7z files and can be found on our GitHub releases page, typically being called ChipWhisperer.Jupyter.7z or similar.

  • Unzip the VirtualBox image, go to Machine > Add in VirtualBox and select the VM that was unzipped.

  • Verify that the VM boots.

Note

If you are on linux you need to add yourself to the vboxusers permission group using, so Virtual Box is given permission to access usb devices:

sudo usermod -aG vboxusers <your username>

Then refresh the groups by restarting your computer or logging out and in again.

Next, we’ll need to update some passwords for the VM. Boot the virtual machine then:

  • Log in (user: vagrant pass: vagrant).

  • Setup a new password for Jupyter. As of release 5.2.0, you will be prompted to set a password on startup if one doesn’t exist for Jupyter. For older releases, simply type jupyter notebook password in the command prompt, then set a password. Note that Jupyter will not start until this is done. This password will be needed to log into Jupyter, so make sure you record it as well.

  • Reboot the VM.

  • Once the VM is booted, you can connect to Jupyter via localhost:8888 ( Firefox/Chrome ONLY). You will be asked for the password you set via jupyter notebook password

You shouldn’t need to log in to the VM again to run Jupyter (which provides the interface) as it should start automatically, but make sure you still record the password you set for the vagrant account, as you will need to log in to update ChipWhisperer.

You are now ready to use ChipWhisperer. Open Chrome/Firefox and type localhost:8888 into the address bar. This will give you access to the Jupyter Notebook server running in the virtual machine.

Updating

For most updates, simply run jupyter/ChipWhisperer Updating.ipynb. The first two code blocks in this notebook will update ChipWhisperer and ChipWhisperer-Jupyter, respectively. Starting with ChipWhisperer 5.6.1, the release page for each version of ChipWhisperer will indicate if it is recommended that you install a new VM image.

Note

Your changes to notebooks likely will not survive a ChipWhisperer-Jupyter update. As such, starting with ChipWhisperer 5.6.1, the contents of the courses, demos, and experiements folders will be copied to the jupyter-backup folder before the update is done.

Windows Installer

Note

Beginning with ChipWhisperer 5.5, the Windows installer includes everything you need to run ChipWhisperer!

Warning

Windows Subsystem for Linux (WSL) seems to interfere with %%bash blocks. If you get an error about not being able to find make, or something about needing to install a Linux distribution, try disabling WSL or changing %%bash to %%sh.

Warning

It is recommended that you enable long paths on Windows to prevent any files from not being copied during installation. Follow https://www.microfocus.com/documentation/filr/filr-4/filr-desktop/t47bx2ogpfz7.html, then reboot to enable long paths

If you want to run a native Windows installation of ChipWhisperer, your best bet is to run the Windows installer, which takes care of getting the prerequisites for you. The steps for using the installer are as follows:

  • Navigate to the ChipWhisperer release page on Github: releases

  • Find the latest ChipWhisperer Windows install executable (currently Chipwhisperer.v5.5.2.Setup.64-bit.exe)

  • Run the executable and choose the path you want to install ChipWhisperer at. You must have read/write permissions for the location you install to, so avoid installing in a location like C:\Program Files or the like. The default install location (the user’s home directory) will work for most users.

  • Choose whether or not you want to create a desktop shortcut for running ChipWhisperer and whether or not you want to install make and compilers (we recommend that you do).

If you’re on firmware x.23 or newer, you’re all set! Drivers will be automatically installed when you plug your ChipWhisperer in. Otherwise, see Windows Drivers.

With this, you now have a fully functioning ChipWhisperer install. Run the ChipWhisperer app, then navigate to the Jupyter folder, where tutorials for running ChipWhisperer are located.

Updating

For most updates, simply run jupyter/ChipWhisperer Updating.ipynb. The first two code blocks in this notebook will update ChipWhisperer and ChipWhisperer-Jupyter, respectively. Starting with ChipWhisperer 5.6.1, the release page for each version of ChipWhisperer will indicate if it is recommended that you reinstall using a new Windows exe.

Note

Your changes to notebooks likely will not survive a ChipWhisperer-Jupyter update. As such, starting with ChipWhisperer 5.6.1, the contents of the courses, demos, and experiements folders will be copied to the jupyter-backup folder before the update is done.

ChipWhisperer

Note

You must have the Prerequisites for your system installed before continuing with the installation of the repository.

Note

You may have to replace all the calls to python on the command line with whatever gives you access to the python version you installed. On GNU/Linux you will probably use python3, or you can use the full path to the python interpreter. It is not required but recommended to use a virtual environment.

After satisfying prerequisites for your system, install the ChipWhisperer repository/package using one of:

Git (Recommended)

The best way to get the ChipWhisperer software, as well as drivers, hardware source code, and Jupyter Notebook tutorials.

PyPi

The classic pip install chipwhisperer. Does not install the hardware source code or Jupyter Notebooks.

GitHub Releases

Get the latest stable release from the GitHub repository. The release includes hardware source code, but no Jupyter Notebooks currently.

Git

The recommended way to install ChipWhisperer natively is by cloning it from Git. By default this will pull in the develop version, which has all the latest features/bug fixes, but we also keep each major release on master.

Note

On Unix based OS (Mac, Linux, etc), python often links to python2. You may need to replace python calls with python3 (e.g. python3 -m pip install... instead of python -m pip install....)

If you have Git already set up, this is easy to do:

git clone https://github.com/newaetech/chipwhisperer.git
cd chipwhisperer

# To get the jupyter notebook tutorials
git submodule update --init jupyter
python -m pip install -r jupyter/requirements.txt --user

# enable jupyter interactive widgets
jupyter nbextension enable --py widgetsnbextension

# use pip to install in develop mode
python -m pip install -e . --user

The user flag installs ChipWhisperer in the user’s local python site-packages directory.

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 update --init openadc
cd openadc/controlsw/python
python -m pip install -e . --user

Once ChipWhisperer is installed, you can run chipwhisperer.

You can update ChipWhisperer by running git pull in both the chipwhisperer and jupyter folders.

PyPi

If you want to use chipwhisperer as a standalone python package and are not interested in having all the tutorials and extra jupyter notebook stuff, this installation method is for you:

pip install chipwhisperer

Will install the chipwhisperer/software/chipwhisperer python package in your site packages. Now you can go play around with the Python API, or take a look at some example tutorials The tutorials are all written in jupyter notebook, which you don’t have using this installation method. However, you can still take a look at the procedure and the code, and use it as an example of what can be accomplished using chipwhisperer.

You can update by running:

pip install --upgrade chipwhisperer

GitHub Releases

ChipWhisperer is also available as a Github release. This version won’t come with Jupyter tutorials and will be more difficult to update, so it isn’t recommended.

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 VBox 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, install the python dependencies and run the Python install procedure (setup.py) using pip. Use the -e flag for develop mode 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 chipwhisperer
python -m pip install -e . --user

# to be able to run jupyter and the tutorials
pip install -r jupyter/requirements.txt --user

# enable jpyter interactive widgets
jupyter nbextension enable --py widgetsnbextension

To test, run python and try importing the chipwhisperer module:

>>> import chipwhisperer as cw

If you want to run the tutorials you can now start the Jupyter Notebook server.

Virtual Machine (VMWare)

For various reasons, such as licensing and USB support, users may prefer to run ChipWhisperer through VMWare instead of VirtualBox. A VMWare compatable image is not provided with ChipWhisperer releases, but such an image can be easily converted from the provided image using VirtualBox

  • Install VirtualBox

  • Download a ChipWhisperer virtual machine image release or build it yourself using Vagrant. Virtual machine images can be found on our Github releases

  • Add the VM image to VirtualBox

  • Right click on the image in VirtualBox and select Export to OCI

  • Select OVF Format 1.0 and export using the default settings.

  • The resulting .ovf file can be opened in VMWare. VMWare may complain about the file not following OVF specifications. If this happens, hit retry.

You should now have a working VMWare image. Boot the VM and add passwords as described in Virtual Machine (VirtualBox) Before logging out, run the following command and record the eth0 IP Address:

ip addr

The final step is to setup VMWare port forwarding:

  • If you have VMWare Player, you’ll need to install VMWare Workstation Pro. The required utility tool does not require a license to run, so Workstation Pro can be installed without purchasing the software. If you’re already running Workstation Pro, you can skip this step.

  • Navigate to the folder where VMWare Workstation Pro is installed and run vmnetcfg.exe

  • Click the Change Settings button.

  • Click on the NAT table entry (typically VMnet8) and click on NAT Settings... Take note of the Subnet Address of this entry

  • Under the Port Fowarding table, click Add and fill in the following settings:

    • Host port:                  8888

    • Type:                       TCP

    • Virtual machine IP address: <subnet address>

    • Virtual machine port:       8888

    • Description:                Jupyter (optional)

  • Hit OK until vmnetcfg.exe is closed

You should now be able to open the VM and connect to <eth0 IP>:8888, replacing <eth0 IP> with the IP address you recorded after running ip addr.