```
#!htmlcomment

This page is maintained automatically by a script.  Don't modify this page by hand,
your changes will just be overwritten the next time the script runs.  Talk to your
Friendly Neighborhood Repository Maintainer if you need to change something here.

```

```
#!html
<h1>Toys to test Cryptech Alpha HSM with OpenSSL engine API</h1>

<p>Packages you need (on Debian Jessie, anyway):</p>

<pre><code>sudo apt-get install opensc cryptech-alpha stunnel micro-httpd w3m
sudo apt-get install -t jessie-backports libengine-pkcs11-openssl
</code></pre>

<p>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.</p>

<p>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.</p>

<h2>Configuration</h2>

<ul>
<li><p><code>openssl.conf</code> 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.</p></li>
<li><p><code>environment.sh</code> 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.</p></li>
</ul>

<h2>Scripts</h2>

<ul>
<li><p><code>create-keys.sh</code> uses <code>pkcs11-tool</code> to create several test keys.</p></li>
<li><p><code>list-keys.sh</code> uses <code>pkcs11-tool</code> to list keys known to the HSM.</p></li>
<li><p><code>delete-keys.sh</code> uses <code>pkcs11-tool</code> to delete the keys which
<code>create-keys.sh</code> created.</p></li>
<li><p><code>issue-certificates.sh</code> generates a small X.509v3 certificate tree.
As a sanity check, it also verifies the issued certificates.
This depends on the keys created by <code>create-keys.sh</code>.</p></li>
<li><p><code>basic-signature.sh</code> performs a basic hash-and-sign of a data file
using the <code>openssl dgst</code> 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 <code>issue-certificates.sh</code>).</p></li>
<li><p><code>smime-signature.sh</code> generates and verifies a signed S/MIME message;
this also depends on <code>issue-certificates.sh</code>.</p></li>
<li><p><code>https-server.sh</code> runs a toy https server, using keys and certificates
generated by <code>create-keys.sh</code> and <code>issue-certificates.sh</code>.</p></li>
<li><p><code>https-client.sh</code> uses w3m as a client to talk to the toy server
run by <code>https-server.sh</code> (and therefore has the same dependencies).</p></li>
</ul>

<h2>References and notes</h2>

<ul>
<li><a href="https://www.nlnetlabs.nl/downloads/publications/hsm/">https://www.nlnetlabs.nl/downloads/publications/hsm/</a></li>
<li><a href="https://github.com/OpenSC/OpenSC/wiki">https://github.com/OpenSC/OpenSC/wiki</a></li>
<li><a href="https://wiki.openssl.org/index.php/Command_Line_Utilities">https://wiki.openssl.org/index.php/Command_Line_Utilities</a></li>
<li><a href="https://www.openssl.org/docs/man1.0.2/apps/">https://www.openssl.org/docs/man1.0.2/apps/</a></li>
</ul>

<p>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
<code>apps/</code> 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 <code>PEM</code>, one of the supported
formats is <code>ENGINE</code>, in which case the "filename" is interpreted as a
key selector.</p>
```

[[RepositoryIndex(format=table,glob=user/sra/openssl-engine)]]

| Clone `https://git.cryptech.is/user/sra/openssl-engine.git` |
|---|