From 3185360834dc9992c141c84517bdecd3a87312a1 Mon Sep 17 00:00:00 2001 From: Rob Austein Date: Sun, 21 Aug 2016 12:17:19 -0400 Subject: Scripts demonstrating the OpenSSL engine API with Cryptech Alpha HSM. --- README.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 README.md (limited to 'README.md') 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. + + -- cgit v1.2.3