diff options
Diffstat (limited to 'content/UpgradeToKSNG.md')
| -rw-r--r-- | content/UpgradeToKSNG.md | 194 |
1 files changed, 194 insertions, 0 deletions
diff --git a/content/UpgradeToKSNG.md b/content/UpgradeToKSNG.md new file mode 100644 index 0000000..bb4d02d --- /dev/null +++ b/content/UpgradeToKSNG.md @@ -0,0 +1,194 @@ +Title: UpgradeToKSNG +Author: sra +Date: 2016-12-22 22:33 +Modified: 2016-12-22 22:53 + + + +# 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 [BinaryPackages]({filename}BinaryPackages.md). + +### 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](https://git.cryptech.is/sw/stm32.md). + +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. |