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.

  1. 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 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 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.