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