From b092ffbcbe2c9398494f7dc9db6f0796971633e0 Mon Sep 17 00:00:00 2001 From: Rob Austein Date: Sun, 13 Sep 2020 23:04:30 +0000 Subject: Import Cryptech wiki dump --- raw-wiki-dump/Upgrading | 186 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 186 insertions(+) create mode 100644 raw-wiki-dump/Upgrading (limited to 'raw-wiki-dump/Upgrading') diff --git a/raw-wiki-dump/Upgrading b/raw-wiki-dump/Upgrading new file mode 100644 index 0000000..d85368c --- /dev/null +++ b/raw-wiki-dump/Upgrading @@ -0,0 +1,186 @@ + [[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 [https://backports.debian.org/Instructions/ `jessie-backports`] 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: + +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 + +^] +}}} -- cgit v1.2.3