1 files changed, 195 insertions, 0 deletions
diff --git a/content/Upgrading.md b/content/Upgrading.md
new file mode 100644
index 0000000..ffeb2ef
--- /dev/null
+++ b/content/Upgrading.md
@@ -0,0 +1,195 @@
+Title: Upgrading
+Author: ln5
+Date: 2017-05-12 23:15
+Modified: 2018-04-07 23:03
+
+ 
+
+# 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 [UpgradeToKSNG]({filename}UpgradeToKSNG.md). 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
+
+^]
+```