Installation¶
You get your choice of installing ChipWhisperer and its prerequisites: the easy way or the hard way.
- Basic
Windows Installer (Windows 10 recommended)
Virtual Machine (VirtualBox) (Recommended)
- 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, hitretry
.
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 onNAT 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
untilvmnetcfg.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
.