From 891730d13b324fad916572a82f0bd610c5de9aad Mon Sep 17 00:00:00 2001 From: Rob Austein Date: Sun, 13 Sep 2020 23:06:24 +0000 Subject: Rename for conversion --- raw-wiki-dump/UpgradeToKSNG | 184 -------------------------------------------- 1 file changed, 184 deletions(-) delete mode 100644 raw-wiki-dump/UpgradeToKSNG (limited to 'raw-wiki-dump/UpgradeToKSNG') diff --git a/raw-wiki-dump/UpgradeToKSNG b/raw-wiki-dump/UpgradeToKSNG deleted file mode 100644 index 1120a7b..0000000 --- a/raw-wiki-dump/UpgradeToKSNG +++ /dev/null @@ -1,184 +0,0 @@ -[[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