Import Cryptech wiki dump

1 files changed, 184 insertions, 0 deletions

diff --git a/raw-wiki-dump/UpgradeToKSNG b/raw-wiki-dump/UpgradeToKSNG
new file mode 100644
index 0000000..1120a7b
--- /dev/null
+++ b/raw-wiki-dump/UpgradeToKSNG
@@ -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