Slug: Upgrading
Title: Upgrading the Cryptech Alpha HSM
Date: 2017-05-12 23:15
Modified: 2018-04-07 23:03
Category: Releases
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.
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.
A few intrepid users are already testing the 'ksng' development branch,
using the instructions at 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.
$ 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 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).
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:
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.
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.
(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.)
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
^]
$ cryptech_upload --firmware --user wheel
PIN: YouReallyNeedToChangeThisPINRightNowWeAreNotKidding
$ cryptech_upload --bootloader --user wheel --simon-says-whack-my-bootloader
PIN: YouReallyNeedToChangeThisPINRightNowWeAreNotKidding
This upgrade includes an experimental ECDSA point multiplier in hardware,
which the firmware will use if present.
$ cryptech_upload --fpga --user wheel
PIN: YouReallyNeedToChangeThisPINRightNowWeAreNotKidding
$ 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
^]
