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.

## 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]({filename}UpgradeToKSNG.md). 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

^]
```