Hack images, store outputs in git again for now

Easier to track what each script change does if we keep the before and
after versions of the markdown in git too.  Clean this up eventually,
but simplifies development.

1 files changed, 192 insertions, 0 deletions

diff --git a/markdown/UpgradeToKSNG.md b/markdown/UpgradeToKSNG.md
new file mode 100644
index 0000000..d33c834
--- /dev/null
+++ b/markdown/UpgradeToKSNG.md
@@ -0,0 +1,192 @@
+[[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.