From b092ffbcbe2c9398494f7dc9db6f0796971633e0 Mon Sep 17 00:00:00 2001 From: Rob Austein Date: Sun, 13 Sep 2020 23:04:30 +0000 Subject: Import Cryptech wiki dump --- raw-wiki-dump/UpgradeToKSNG | 184 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 184 insertions(+) create mode 100644 raw-wiki-dump/UpgradeToKSNG (limited to 'raw-wiki-dump/UpgradeToKSNG') 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: + +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 -- cgit v1.2.3