1 files changed, 184 insertions, 0 deletions
diff --git a/tracwiki/UpgradeToKSNG.trac b/tracwiki/UpgradeToKSNG.trac
new file mode 100644
index 0000000..1120a7b
--- /dev/null
+++ b/tracwiki/UpgradeToKSNG.trac
@@ -0,0 +1,184 @@
+[[PageOutline]]
+
+= Upgrading Cryptech Alpha HSM to "ksng" development package =
+
+This page attempts to explain the upgrade procedure for testing out
+the new "ksng" development branch of the Cryptech Alpha firmware.
+
+== Cavats ==
+
+This particular upgrade is more complicated than we would have
+preferred, due to the interaction of two unrelated factors:
+
+1. As the name (obscurely) implies, the main feature in the ksng
+   branch is a completely new HSM keystore implementation, which makes
+   better use of the Alpha's keystore flash, allows a much larger
+   number of keys, removes the need for an SQL database on the host,
+   gets your laundry 25% brighter, and leaves your breath alone.
+
+   We did not attempt to provide any sort of backwards compatability
+   to the old 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.
+
+2. The "Device Field Upgrade" (DFU) capability in the Alpha's firmware
+   was a last-minute addition before the Berlin workshop in July 2016,
+   and, as last minute additions often do, it turned out to be buggy.
+   There are three distinct pieces of software involved in the upgrade
+   process, and they were all slightly buggy, in different ways.
+   Because of this, one must perform the upgrade steps in a particular
+   order to avoid bricking the HSM.  The upgrade includes fixes for
+   all the (known) bugs in the DFU process, so we hope that this will
+   be a one-time annoyance (famous last words).
+
+If something goes horribly wrong and you do somehow manage to brick
+your Alpha, don't give up, recovery is still possible, it just
+requires an ST-LINK debugger and cable (more on this below).
+
+== Overview ==
+
+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.
+
+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.
+
+This upgrade procedure was tested on Debian Jessie, with an Alpha
+whose firmware had been rolled back to the version from the Berlin
+workshop (APT/Homebrew package version 2.0.1468584175, commit
+cd445b69b2caa7205f4e1c368aa2c6bf8c2d7692 in repository
+https://git.cryptech.is/releng/alpha.git).
+
+== Install cryptech-alpha-ksng package using apt-get or Homebrew ==
+
+Binaries for the "ksng" branch are available as a separate set of
+"cryptech-alpha-ksng" packages, which replace the "cryptech-alpha"
+packages for the master branch.  This seemed the simplest way of
+letting people experiment with the new code while falling back to the
+old if necessary.  The "cryptech-alpha-ksng" packages are declared to
+conflict with the "cryptech-alpha" packages, because they install
+programs by the same name in the same places and you need the version
+of the host software which goes with the HSM firmware your running.
+
+APT handles package conflicts differently from the way that Homebrew
+does.  If you have "cryptech-alpha" installed and try to install
+"cryptech-alpha-ksng", APT assumes you meant what you said and will
+just replace the old package with the new one.  Homebrew, on the other
+hand, reports the conflict and refuses to proceed until you sort it out.
+
+The following assumes that you already had the Cryptech APT repository
+or Homebrew tap configured; if not, see  [[wiki:BinaryPackages]].
+
+=== Installing cryptech-alpha-ksng package using apt-get on Debian or Ubuntu Linux ===
+
+{{{
+$ sudo apt-get update
+$ sudo apt-get install cryptech-alpha-ksng
+}}}
+
+=== Installing cryptech-alpha-ksng package using Homebrew on OSX ===
+
+{{{
+$ brew update
+$ brew uninstall cryptech-alpha
+$ brew install cryptech-alpha-ksng
+}}}
+
+== 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 -v`
+}}}
+
+== Clear the keystore flash ==
+
+Sorry about this.  Yes, we know we need backup and restore, we'll get
+there.  But for this upgrade, it's safest to wipe the 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
+}}}
+
+== 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
+
+^]
+}}}
+
+== What to do if you manage to brick your Alpha ==
+
+If the above procedure somehow goes horribly wrong and bricks your
+alpha, you can still recover, but you'll need an ST-LINK programmer.
+There's some discussion of this at [[wiki:GitRepositories/sw/stm32]].
+
+Possible sources for the ST-LINK programmer and a suitable cable:
+
+* http://www.mouser.com/search/ProductDetail.aspx?R=0virtualkey0virtualkeyNUCLEO-F411RE
+* https://www.sparkfun.com/products/10376
+
+These are relatively cheap, you'll probably pay as much for the
+postage as for the parts themselves.  If you have a better source, go
+for it.
+
+The programmer is the important part, you can use any sort of cabling
+you like so long as it connects the right pins of the programmer to
+the corresponding pins on the Alpha; the SparkFun cable just happens
+to be a tidy package which matches the relevant SWD headers.
+
+We'll include a more detailed description of the recovery process here
+if anybody needs it, but the short version is:
+
+* Install OpenOCD on your host machine.
+* Open up the Alpha's case, take the board out.
+* Connect the programmer and power the board back up.
+* Use the `flash-target` script from the `sw/stm32` repository to
+  stuff the `hsm.elf` and `bootloader.elf` files from the binary
+  firmware tarball into the HSM.
+* Power down, disconnect the programmer, put the Alpha back in its
+  case, done.
+\ No newline at end of file