Start restructuring for Pelican

1 files changed, 0 insertions, 184 deletions

diff --git a/tracwiki/UpgradeToKSNG.trac b/tracwiki/UpgradeToKSNG.trac
deleted file mode 100644
index 1120a7b..0000000
--- a/tracwiki/UpgradeToKSNG.trac
+++ /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