1 files changed, 57 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..648a565
--- /dev/null
+++ b/README.md
@@ -0,0 +1,57 @@
+# 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/SmartCardHSM
+* 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.
+
+