[Cryptech Core] Alpha software cheat sheet

[Rob Austein]

More polished version of this will go into workshop instructions,
slides, Wiki, ..., but for the impatient with access to an Alpha
board, here's how to use the packaged stuff:

Installation: see https://wiki.cryptech.is/wiki/BinaryPackages

We supply binaries for Ubuntu Xenial and Debian Jessie.

We supply a source package (Homebrew) for OSX; we have the technical
capability to generate binary packages for OSX as well, but Apple's
SDK license forbids it unless we spend money on Apple hardware; while
I have nothing against the horse that rode in on, to hell with that.
So for OSX you'll have to put up with a big source package and wait a
few minutes while Homebrew compiles it for you.

What gets installed is fairly minimal.  Directory and filename suffix
conventions are OS-specific, in general we try to do the obvious
thing:

  Linux:	base=/usr	so=so
  OSX:		base/usr/local	so=dylib

The PKCS #11 library itself is installed in $base/lib/libpkcs11.$so.

Scripts are installed in $base/sbin (for reasons that seemed to make
sense at the time, but maybe that should be $base/bin instead for user
convenience?).

Firmware tarball goes in $base/share/cryptech-alpha-firmware.tar.gz.

Configuration of things like the USB port that libpkcs11 should use is
done via environment variables (not ideal, but what we could do with
what we have at the moment -- discussion topic after the workshop).

The cryptech_probe script exists to figure out what those environment
variable settings should be, and set them for you if you trust it to
do that.  Works somewhat like ssh-agent:

  $ eval `cryptech_probe`

If you want cryptech_probe to natter a bit about what it finds:

  $ eval `cryptech_probe -v`

There's also a debugging option which will display the full horror
(not recommended if you've eaten recently).

Once you've run cryptech_probe (or set the necessary environment
variables by hand if you prefer), the rest of the code should be able
to find the HSM's console and RPC ports without further hints.

cryptech_upload is a fancy version of Fredrik's original DFU script,
with bells and whistles to let it pull firmware from the installed
firmware tarball, so you can just tell it which what you want to
upgrade (--firmware, --fpga, or, if you really like living
dangerously, the HSM's bootloader) and it will pull the appropriate
image from the current firmware tarball.

cryptech_miniterm is a tiny script which runs a terminal emulator on
the HSM's console port.  It's not the best terminal emulator in the
world, but we got it for free along with the PySerial package, which
we needed for other purposes, and for a six line script (two lines if
this were an Obfuscated Python contest), it's pretty usable.  Users
are of course free to use a different emulator (eg, picoterm).

That's about it from the end-user point of view.  There is of course a
lot of stuff under the hood here, but the user shouldn't need to know
about most of it.

The above is not quite enough to set up the HSM, there's some console
voodoo that Fredrik might want to describe, since he's the only person
who really knows how he intended some of the commands to work. :)

Time permitting, we may try to clean this up a bit more, but we're
getting down to the wire for Berlin, so it's probably best to consider
a code freeze to be in effect for anything that's not critical to
success of the workshop.

Last: At the moment, generation of new packages is manual, I have to
push a button.  We could automate this to run under cron without much
additional work, did not seem a priority at the moment.

I will probably promote the package generation stuff to
git.cryptech.is/releng/alpha sometime this weekend (right now it's
under .../user/sra/).  I may promote the old Novena releng stuff at
the same time, even though it probably doesn't run correctly with the
current code base and we may never need it for anything again.