diff options
Diffstat (limited to 'raw-wiki-dump/Upgrading.md')
| -rw-r--r-- | raw-wiki-dump/Upgrading.md | 190 |
1 files changed, 0 insertions, 190 deletions
diff --git a/raw-wiki-dump/Upgrading.md b/raw-wiki-dump/Upgrading.md deleted file mode 100644 index bfc9106..0000000 --- a/raw-wiki-dump/Upgrading.md +++ /dev/null @@ -1,190 +0,0 @@ - [[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 [`jessie-backports`](https://backports.debian.org/Instructions/) 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 - -^] -``` |