# Toys to test Cryptech Alpha HSM with OpenSSL engine API

Packages you need (on Debian Jessie, anyway):

    sudo apt-get install libengine-pkcs11-openssl opensc opensc-pkcs11 cryptech-alpha

General plan here is to use pkcs11-tool to create keys, then use the
pkcs11 OpenSSL engine and OpenSSL command line tool to do vaguely
useful things with those keys.

## Configuration

* `openssl.conf` contains two different kinds of OpenSSL voodoo: the
  bits needed to configure the engine, and the bits needed to
  construct X.509 certificates.  The engine configuration uses
  environment variables to minimize the number of places where the
  same information needs to be configured.

* `environment.sh` is where environment variables are configured,
  including the PKCS #11 PIN: you would not want to handle the PIN
  this way in production!  But it's convenient for a test script.

## Scripts

* `create-keys.sh` uses `pkcs11-tool` to create several test keys.  At
  the moment these are all RSA: the HSM is quite capable of using EC
  P-256, P-384, and P-521 keys, but the engine seems not to like them.

* `list-keys.sh` uses `pkcs11-tool` to list keys known to the HSM.

* `delete-keys.sh` uses `pkcs11-tool` to delete the keys which
  `create-keys.sh` created.

* `basic-signature.sh` performs a basic hash-and-sign of a data file
  using the `openssl dgst` command, writing a detached signature out
  as a binary file.  As a sanity check, it also verifies the resulting
  signature using the corresponding public key.

* `smime-signature.sh` generates a small X.509v3 certificate tree and
  uses that to generate a signed S/MIME message.

## References and notes

* <https://www.nlnetlabs.nl/downloads/publications/hsm/>
* <https://github.com/OpenSC/OpenSC/wiki>
* <https://wiki.openssl.org/index.php/Command_Line_Utilities>
* <https://www.openssl.org/docs/man1.0.2/apps/>

Given the overall state of OpenSSL's documentation, it also helps to
be able to read the OpenSSL source code: in this particular case, the
`apps/` directory is most likely to be useful.  It turns out that many
(not all) places where one of the OpenSSL command line functions allow
one to specify a key format other than `PEM`, one of the supported
formats is `ENGINE`, in which case the "filename" is interpreted as a
key selector.