{ "cells": [ { "cell_type": "markdown", "id": "4b61907d", "metadata": {}, "source": [ "# Chipwhisperer installation, set up and use" ] }, { "cell_type": "markdown", "id": "3cb695af", "metadata": {}, "source": [ "It can be difficult to install, set up and use new software. In this case, we also combine it with hardware which can make troubleshooting even more difficult. This notebook takes an easy route to the installation, set up, and use of ChipWhisperer." ] }, { "cell_type": "markdown", "id": "b33b3da5", "metadata": {}, "source": [ "# Installation" ] }, { "cell_type": "markdown", "id": "e3413377", "metadata": {}, "source": [ "## VM installation " ] }, { "cell_type": "markdown", "id": "78adebd8", "metadata": {}, "source": [ "We would highly recommend using a virtual machine when using Chipwhisperer. When using a VM, there is not much to install other than the machine and the image to run, you may need to update the firmware as you go, but there is a notebook for this in the machine. Here is a step by step to install VirtualBox and the ChipWhisperer image. \n", "\n", "- Install VirtualBox.https://www.virtualbox.org/wiki/Downloads\n", "This program is freely available on Windows, Mac, and Linux. Although, as of 02.08.23, they have removed the beta for apple silicon.\n", "\n", "- Install the VirtualBox Extension pack, found on the VirtualBox downloads page linked above. This is necessary for the VM to interact with the ChipWhisperer hardware. Note that the license for the Extension pack differs from the base VirtualBox license: https://www.virtualbox.org/wiki/VirtualBox_PUEL\n", "- Download a ChipWhisperer virtual machine image release or build it yourself using Vagrant. VM images come as .7z files and can be found on the GitHub releases page, typically called ChipWhisperer.Jupyter.7z or similar. Find the latest release from this link https://github.com/newaetech/chipwhisperer/releases\n", " The latest release for VM is 5.6.1 as of 02.08.23.\n", "- Unzip the VirtualBox image, go to Machine > Add in VirtualBox and select the VM that was unzipped.\n", "- Verify that the VM boots.\n", "\n", "Note:\n", "If you are on Linux, you need to add yourself to the vboxusers permission group using, so Virtual Box is permitted to access USB devices:\n", "\n", "```sudo usermod -aG vboxusers ```\n", "\n", "Then refresh the groups by restarting your computer or logging out and in again.\n", " \n", "Next, we’ll need to update some passwords for the VM. Boot the virtual machine then:\n", "\n", "- Log in (user: vagrant pass: vagrant).\n", "- Set up 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, type the 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.\n", "- Reboot the VM.\n", "- 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\n", "\n", "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.\n", "\n", "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 in the virtual machine.\n", "\n", "This guide is almost the same as ChipWhisperer’s since it is very straightforward and difficult to do wrong. https://chipwhisperer.readthedocs.io/en/latest/virtual-box-inst.html \n" ] }, { "cell_type": "markdown", "id": "3f07b2ab", "metadata": {}, "source": [ "## Windows install\n", "\n", "If you want to avoid using a VW, just follow ChipWhisperer’s own installation guide. It is very thorough, and you should be fine following it. https://chipwhisperer.readthedocs.io/en/latest/windows-install.html" ] }, { "cell_type": "markdown", "id": "d9be9fc2", "metadata": {}, "source": [ "## Linux install\n", "\n", "The Linux installation guide is also quite easy to follow, so just do the steps in this link: https://chipwhisperer.readthedocs.io/en/latest/linux-install.html" ] }, { "cell_type": "markdown", "id": "40775e34", "metadata": {}, "source": [ "## Apple silicon installation" ] }, { "cell_type": "markdown", "id": "0834356a", "metadata": {}, "source": [ "Due to the different architecture on Apple silicon, it can sometimes be a bit of a struggle to deal with the installation of Chipwhisperer. In this notebook, common error messages are dealt with and/or links with solutions are presented/attached. We follow Chipwhisperer's installation guide https://chipwhisperer.readthedocs.io/en/latest/mac-install.html.\n", "\n", "### Setting up bash\n", "\n", "Since zsh is the default on Mac we should switch to a bash shell to install Brew. You can install brew using zsh, but we need bash for ChipWhisperer so just set it as default. Run `chsh -s /bin/bash` in a terminal window or follow this link https://www.howtogeek.com/444596/how-to-change-the-default-shell-to-bash-in-macos-catalina/. Then refresh the terminal window using `source ~/.bashrc` or open a new one.\n", "\n", "### Installing Brew\n", "\n", "The presented link, from ChipWhisperer, for installing Brew doesn't work anymore, so go to Brew's website and copy it instead (https://brew.sh). Brew usually manages itself, so no problems should occur. Consult https://docs.brew.sh/Common-Issues if any issues occur.\n", "\n", "### Python\n", "\n", "As ChipWhisperer recommends the use of pyenv to install Python, we follow this approach. Here is a step by step of commands to type in your terminal window:\n", "- ```brew install pyenv```\n", "- ```pyenv install 3.9.5``` \n", "\n", "You could install a different version, but this is what Chipwhisperer recommends. Just make sure that you are using something newer than 3.7.5\n", "\n", "- ```pyenv global 3.9.5```\n", "\n", " and verify it worked \n", " \n", "- ```pyenv version ```\n", "\n", "you should see\n", "- ``` 3.9.5 (set by /Users//.pyenv/version) ```\n", "\n", "Now type \n", "- ``` echo -e 'if command -v pyenv 1>/dev/null 2>&1; then\\n eval \"$(pyenv init -)\"\\nfi' >> ~/.bashrc ```\n", "\n", "Now our dotfile should include \n", "\n", "```\n", "if command -v pyenv 1>/dev/null 2>&1; then\n", " eval \"$(pyenv init -)\"\n", "fi \n", "```\n", "\n", "\n", " You could also just follow this link https://opensource.com/article/19/5/python-3-default-mac, and you can get Python up and running, but remember that they use an outdated version of Python here, and they are not using a bash shell. \n", " \n", "This way of handling a Python environment is much better than using Anaconda as it is easier to handle different environments. If you experience trouble with different directories when installing Python, such as another version already installed as \n", " `/usr/local/bin/python` \n", "then run \n", "* ` echo \"alias python=/usr/local/bin/python3\" >> ~/.bashrc` \n", "* ` source ~/.bashrc` \n", "\n", "### Libusb\n", "\n", "You should install libusb1; `brew install libusb` or `pip install libusb1` \n", "\n", "### ARM compiler\n", "\n", "Use this link: https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads and not the one from the ChipWhisperer website since that is an outdated version.\n", "\n", "### AVR compiler\n", "\n", "AVR is installed with brew, and you just need to run commands directly in the terminal. \n", "\n", " `brew tap osx-cross/avr` \n", "\n", " `brew install avr-gcc` \n", "\n", "### Make\n", "\n", "Apple issues their computers with an old version of make, 3.81, which is not compatible with ChipWhisperer.\n", "Type ``` brew install make ``` in a terminal window or go to (https://formulae.brew.sh/formula/make), and follow the instructions from there.\n", "\n", "\n", "\n", "If you have any trouble running make when setting up firmware during the labs, just run gmake instead or write\n", "\n", "```export PATH=\"/usr/local/opt/make/libexec/gnubin:$PATH\"``` or the command Brew suggests in your bash shell. This issue can occur since brew installs make as gmake.\n" ] }, { "cell_type": "markdown", "id": "266c1941", "metadata": {}, "source": [ "## Git\n", "\n", "You can also use git to download ChipWhisperer. We recommend this if you don't use a VM since it is easy to update when needed, and you usually don't get any PATH errors or difficulties. If you don't have git installed, grab it from here https://git-scm.com/downloads and choose your preferred release.\n", "\n", "Now you can insert the following commands in the bash shell\n", "\n", "```\n", "git clone https://github.com/newaetech/chipwhisperer.git\n", "cd chipwhisperer\n", "git checkout develop\n", "cd software\n", "python setup.py develop --user\n", "\n", "```\n", "And for the jupyter repo\n", "\n", "```\n", "cd ..\n", "git submodule init jupyter/\n", "git submodule update\n", "```\n", "And OpenADC\n", "```\n", "cd ..\n", "git submodule init\n", "git submodule update\n", "cd openadc/controlsw/python\n", "python setup.py develop --user\n", "```\n", "Once ChipWhisperer and the Jupyter notebooks are installed, you can run the tutorials through Jupyter by typing\n", "```\n", "jupyter notebook\n", "```\n", "into the command prompt, which should open a new Window in your browser. Navigate to chipwhisperer/software/jupyter/ to get started with the new Jupyter tutorials.\n", "Note that you still have to install all the compilers and other necessities for things to work.\n", "These commands are taken from this link. https://wiki.newae.com/V5:Installing_ChipWhisperer" ] }, { "cell_type": "markdown", "id": "dc0bc0df", "metadata": {}, "source": [ "## Generic set up\n", "\n", "To get started, you should read and run the notebook Lab 0 - SCA101 setup. https://github.com/newaetech/chipwhisperer-jupyter/blob/abcf669899cead764e57e4ecf5cc8e5c99cb499e/courses/sca101/Lab%200%20-%20SCA101%20Setup.ipynb. \n", "In this lab, there are links to other notebooks that show you how to use jupyter and set up your hardware. In the notebook regarding hardware, there is an error regarding the SimpleSerial protocol version 2. You can't use SS_VER_2_0, you should use the newer SS_VER_2_1 or the old SS_VER_1_1.\n", "\n", "It is important to remember that for the setup to work, you must clearly specify what kind of hardware you are using. An example when using STM32F3 target is\n", "```python\n", "SCOPETYPE = 'OPENADC'\n", "PLATFORM = 'CW308_STM32F3'\n", "CRYPTO_TARGET = 'TINYAES128C'\n", "SS_VER='SS_VER_1_1`\n", "```\n", "It is also important to use the API documentation to your advantage because it gives you a lot of answers to questions you might have about how things work. https://chipwhisperer.readthedocs.io/en/latest/index.html#api" ] }, { "cell_type": "markdown", "id": "7d960eea", "metadata": {}, "source": [ "You should now be able to run through most of the labs without to many difficulties\n", "\n", "NB: When doing the Fault injection labs, you should use a SMA Tee converter so that you can have both a glitching cable and a measuring cable connected to the VOUT port on the CW-UFO board." ] } ], "metadata": { "kernelspec": { "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.9.5" } }, "nbformat": 4, "nbformat_minor": 5 }