diff options
Diffstat (limited to 'markdown/Upgrading.md')
| -rw-r--r-- | markdown/Upgrading.md | 190 |
1 files changed, 190 insertions, 0 deletions
diff --git a/markdown/Upgrading.md b/markdown/Upgrading.md new file mode 100644 index 0000000..bfc9106 --- /dev/null +++ b/markdown/Upgrading.md @@ -0,0 +1,190 @@ + [[PageOutline]] + +# Upgrading the Cryptech Alpha HSM + +This page explains how to upgrade the Cryptech Alpha firmware, bootloader, +and FPGA bitstream (as needed). + +All of the operations here use the Alpha's "management" (MGMT) port, +so that cable must be connected to your Linux or OSX host machine. + +## Upgrading from the stock firmware (Berlin workshop or CrowdSupply) + +The main feature of the 3.0 firmware release is a completely new HSM +keystore implementation, which makes better use of the Alpha's keystore +flash, allows a much larger number of keys, and removes the need for an +SQL database on the host. (See ReleaseNotes.) + +We did not attempt to provide any sort of backwards compatability to the +original minimalistic keystore implementation, so this upgrade process +will wipe your keystore. Sorry. More importantly (from the limited +viewpoint of the upgrade process), it will change how the HSM stores its +PINs, which complicates the upgrade process. + +Because we use the bootloader to upgrade the firmware, and the firmware to +upgrade the bootloader, both use the PINs stored in the keystore to login, +so both need to understand the new keystore, so both need to be upgraded. + +Because of the tricky nature of this particular upgrade, you must +perform these steps, in the specified order: + + +* Install the new host software package using APT or Homebrew. +* Wipe the HSM keystore to reset PINs back to the "factory" state. +* Upgrade the main HSM firmware. +* Upgrade the HSM bootloader. +* Log in to upgraded HSM to set PINs, etc. + + +**Upgrading the bootloader before the main firmware will brick your +Alpha.** So don't do that. + +If something goes horribly wrong and you do somehow manage to brick +your Alpha, see DisasterRecovery. + +## Upgrading from 'ksng' + +A few intrepid users are already testing the 'ksng' development branch, +using the instructions at [wiki:UpgradeToKSNG]. In this case, and with future +upgrades, it it not necessary to either wipe the keystore or upgrade the +bootloader. + + +* Install the new host software package using APT or Homebrew. +* Upgrade the main HSM firmware. + + +## Install the cryptech-alpha package + +### using apt-get on Debian or Ubuntu Linux + +``` +$ sudo apt-get update +$ sudo apt-get install cryptech-alpha +``` + +Yes, you have to install it even if you already had it installed, because +APT wants permission before accepting the new package dependencies. + +Or you could instead run: + +``` +$ sudo apt-get upgrade --with-new-pkgs +``` + +but that might upgrade unrelated stuff. + +If you had the '-ksng' package installed, you might then want to run: + +``` +$ sudo apt-get remove cryptech-alpha-ksng +$ sudo apt-get autoclean +``` + +but nothing terrible is likely to happen if you omit those steps. + +If you're running on Debian Jessie, you may need to enable [`jessie-backports`](https://backports.debian.org/Instructions/) and make sure you're getting the `python-serial` and `python-tornado` dependencies from the backports (the versions of those packages in the base Debian Jessie distribution are too old). + +### using Homebrew on OSX + +If you're upgrading from the original firmware (have not installed the `-ksng` package), a normal Homebrew upgrade cycle +should suffice: + +``` +$ brew update +$ brew upgrade +``` + +If you have the `-ksng` package installed, you need to tell Homebrew that you want to switch back: + +``` +$ brew update +$ brew migrate cryptech-alpha-ksng +$ brew update +``` + +In either case, you might then want to do something like: + +``` +$ brew cleanup +``` + +but nothing terrible is likely to happen if you omit that step. + +If you've tried doing this and nothing happens, you might be hitting a known old bug in Homebrew itself. Make sure your copy of Homebrew is up to date, and if that still doesn't work, try deinstalling whichever `cryptech-alpha*` package you have installed and reinstalling `cryptech-alpha`. + +## Set usual CRYPTECH_* environment variables + +The upgrade process uses the `CRYPTECH_CTY_CLIENT_SERIAL_DEVICE` +environment variable. The easiest way to set it is by using the +`cryptech_probe` script, just as you would for other usage of the +Alpha. + +``` +$ eval `cryptech_probe` +``` + +(Note: you can use the new `cryptech_muxd` and `cryptech_console`, but +these instructions assume you are familiar with `cryptech_miniterm`. Or +you could be using `picocom` or `kermit` or something else. Doesn't matter +to us.) + +## Clear the keystore flash + +If you are upgrading from the original firmware, you will need to wipe the +keystore, to avoid confusing the new keystore code. + +The good news is that we have a utility to back up and restore the new +keystore. The bad news is that we don't have a way to back up the old +keystore. + +``` +$ cryptech_miniterm + +Username: wheel +Password: <your-wheel-pin-goes-here> + +cryptech> keystore erase YesIAmSure + +^] +``` + +## Upgrade the main HSM firmware + +``` +$ cryptech_upload --firmware --user wheel +PIN: YouReallyNeedToChangeThisPINRightNowWeAreNotKidding +``` + +## Upgrade the bootloader + +``` +$ cryptech_upload --bootloader --user wheel --simon-says-whack-my-bootloader +PIN: YouReallyNeedToChangeThisPINRightNowWeAreNotKidding +``` + +## (Optional) Upgrade the FPGA bitstream + +This upgrade includes an experimental ECDSA point multiplier in hardware, +which the firmware will use if present. + +``` +$ cryptech_upload --fpga --user wheel +PIN: YouReallyNeedToChangeThisPINRightNowWeAreNotKidding +``` + +## Log in and set PINs, masterkey, etcetera + +``` +$ cryptech_miniterm + +Username: wheel +PIN: YouReallyNeedToChangeThisPINRightNowWeAreNotKidding + +cryptech> keystore set pin wheel fnord +cryptech> keystore set pin so fnord +cryptech> keystore set pin user fnord +cryptech> masterkey set + +^] +``` |