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

^]