aboutsummaryrefslogtreecommitdiff
path: root/README.md
blob: a349537bbefdcf8fdc9f9befa2f3372440081173 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71

   

Toys to test Cryptech Alpha HSM with OpenSSL engine API

Packages you need (on Debian Jessie, anyway):

sudo apt-get install opensc cryptech-alpha stunnel micro-httpd w3m
sudo apt-get install -t jessie-backports libengine-pkcs11-openssl

We're using the backported version of libengine-pkcs11-openssl because we want ECDSA support -- the ancient version that originally shipped with Jessie only supported RSA.

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.

  • 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.

  • issue-certificates.sh generates a small X.509v3 certificate tree. As a sanity check, it also verifies the issued certificates. This depends on the keys created by create-keys.sh.

  • 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 public key extracted from the corresponding certificate (so this depends on issue-certificates.sh).

  • smime-signature.sh generates and verifies a signed S/MIME message; this also depends on issue-certificates.sh.

  • https-server.sh runs a toy https server, using keys and certificates generated by create-keys.sh and issue-certificates.sh.

  • https-client.sh uses w3m as a client to talk to the toy server run by https-server.sh (and therefore has the same dependencies).

References and notes

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.