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/Upgrading | 186 ------------------------------------------------ 1 file changed, 186 deletions(-) delete mode 100644 raw-wiki-dump/Upgrading (limited to 'raw-wiki-dump/Upgrading') diff --git a/raw-wiki-dump/Upgrading b/raw-wiki-dump/Upgrading deleted file mode 100644 index d85368c..0000000 --- a/raw-wiki-dump/Upgrading +++ /dev/null @@ -1,186 +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 [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: - -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 - -^] -}}} -- cgit v1.2.3