1 files changed, 186 insertions, 0 deletions
diff --git a/tracwiki/Upgrading.trac b/tracwiki/Upgrading.trac
new file mode 100644
index 0000000..d85368c
--- /dev/null
+++ b/tracwiki/Upgrading.trac
@@ -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: <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
+
+^]
+}}}