aboutsummaryrefslogtreecommitdiff
path: root/raw-wiki-dump/UpgradeToKSNG
diff options
context:
space:
mode:
authorRob Austein <sra@hactrn.net>2020-09-13 23:06:24 +0000
committerRob Austein <sra@hactrn.net>2020-09-13 23:06:24 +0000
commit891730d13b324fad916572a82f0bd610c5de9aad (patch)
treef46c94ddfff34f15aafe7cac0596716d1c13c412 /raw-wiki-dump/UpgradeToKSNG
parentb092ffbcbe2c9398494f7dc9db6f0796971633e0 (diff)
Rename for conversion
Diffstat (limited to 'raw-wiki-dump/UpgradeToKSNG')
-rw-r--r--raw-wiki-dump/UpgradeToKSNG184
1 files changed, 0 insertions, 184 deletions
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: <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. \ No newline at end of file