Import Cryptech wiki dump

1 files changed, 186 insertions, 0 deletions

diff --git a/raw-wiki-dump/Upgrading b/raw-wiki-dump/Upgrading
new file mode 100644
index 0000000..d85368c
--- /dev/null
+++ b/raw-wiki-dump/Upgrading
@@ -0,0 +1,186 @@
+ [[PageOutline]]

+

+= Upgrading the Cryptech Alpha HSM =

+

+This page explains how to upgrade the Cryptech Alpha firmware, bootloader,

+and FPGA bitstream (as needed).

+

+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.

+

+== Upgrading from the stock firmware (Berlin workshop or !CrowdSupply) ==

+

+The main feature of the 3.0 firmware release is a completely new HSM

+keystore implementation, which makes better use of the Alpha's keystore

+flash, allows a much larger number of keys, and removes the need for an

+SQL database on the host. (See ReleaseNotes.)

+

+We did not attempt to provide any sort of backwards compatability to the

+original 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.

+

+Because we use the bootloader to upgrade the firmware, and the firmware to

+upgrade the bootloader, both use the PINs stored in the keystore to login,

+so both need to understand the new keystore, so both need to be upgraded.

+

+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.

+

+If something goes horribly wrong and you do somehow manage to brick

+your Alpha, see DisasterRecovery.

+

+== Upgrading from 'ksng' ==

+

+A few intrepid users are already testing the 'ksng' development branch,

+using the instructions at [wiki:UpgradeToKSNG]. In this case, and with future

+upgrades, it it not necessary to either wipe the keystore or upgrade the

+bootloader.

+

+* Install the new host software package using APT or Homebrew.

+* Upgrade the main HSM firmware.

+

+== Install the cryptech-alpha package ==

+

+=== using apt-get on Debian or Ubuntu Linux ===

+

+{{{

+$ sudo apt-get update

+$ sudo apt-get install cryptech-alpha

+}}}

+

+Yes, you have to install it even if you already had it installed, because

+APT wants permission before accepting the new package dependencies.

+

+Or you could instead run:

+

+{{{

+$ sudo apt-get upgrade --with-new-pkgs

+}}}

+

+but that might upgrade unrelated stuff.

+

+If you had the '-ksng' package installed, you might then want to run:

+

+{{{

+$ sudo apt-get remove cryptech-alpha-ksng

+$ sudo apt-get autoclean

+}}}

+

+but nothing terrible is likely to happen if you omit those steps.

+

+If you're running on Debian Jessie, you may need to enable [https://backports.debian.org/Instructions/ `jessie-backports`] and make sure you're getting the `python-serial` and `python-tornado` dependencies from the backports (the versions of those packages in the base Debian Jessie distribution are too old).

+

+=== using Homebrew on OSX ===

+

+If you're upgrading from the original firmware (have not installed the `-ksng` package), a normal Homebrew upgrade cycle

+should suffice:

+

+{{{

+$ brew update

+$ brew upgrade

+}}}

+

+If you have the `-ksng` package installed, you need to tell Homebrew that you want to switch back:

+

+{{{

+$ brew update

+$ brew migrate cryptech-alpha-ksng

+$ brew update

+}}}

+

+In either case, you might then want to do something like:

+

+{{{

+$ brew cleanup

+}}}

+

+but nothing terrible is likely to happen if you omit that step.

+

+If you've tried doing this and nothing happens, you might be hitting a known old bug in Homebrew itself.  Make sure your copy of Homebrew is up to date, and if that still doesn't work, try deinstalling whichever `cryptech-alpha*` package you have installed and reinstalling `cryptech-alpha`.

+

+== 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`

+}}}

+

+(Note: you can use the new `cryptech_muxd` and `cryptech_console`, but

+these instructions assume you are familiar with `cryptech_miniterm`. Or

+you could be using `picocom` or `kermit` or something else. Doesn't matter

+to us.)

+

+== Clear the keystore flash ==

+

+If you are upgrading from the original firmware, you will need to wipe the

+keystore, to avoid confusing the new keystore code.

+

+The good news is that we have a utility to back up and restore the new

+keystore. The bad news is that we don't	have a way to back up the old

+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

+}}}

+

+== (Optional) Upgrade the FPGA bitstream ==

+

+This upgrade includes an experimental ECDSA point multiplier in hardware,

+which the firmware will use if present.

+

+{{{

+$ cryptech_upload --fpga --user wheel

+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

+

+^]

+}}}