OpenSSL
This guide explains how to set up OpenSSL to be able to use Securosys HSMs as a backend for key storage and key usage. This integration is done using plugins that connect OpenSSL via the Primus PKCS #11 provider to the HSM.
Some of the scenarios where OpenSSL can be used with an HSM:
- Generating key pairs protected by the HSM
- Generating certificates protected by keys protected by the HSM
- Importing of certificates so they can be protected by the HSM
- Encrypting and decrypting files and documents using keys protected by the HSM
- Signing applications and files with keys protected by the HSM
OpenSSL v3.x
Provider API
OpenSSL v1.x (Engine) on Windows
Engine API (***Deprecated***)
OpenSSL v1.x (Engine)
Engine API (***Deprecated***)
How OpenSSL integrates with HSMs
To use OpenSSL with an HSM, a plugin is needed. This plugin implements OpenSSL's APIs on one side and the PKCS#11 APIs on the other side, and translates between the two. The plugin then makes normal calls to a PKCS#11 provider.
In other words, calls are routed as follows: OpenSSL -> Plugin -> Primus PKCS#11 Provider -> HSM.
In OpenSSL 1.x, the plugin mechanism is called "Engines". In OpenSSL 3.x, "Providers" are the new plugin mechanism. Engines still exist but are deprecated and may be removed in the future. It is recommended to use OpenSSL 3.x with Providers.
Note the difference between an "OpenSSL Provider" (a plugin for OpenSSL) and a "PKCS#11 Provider" (a library that exposes a PKCS#11-compliant API for applications to call).
Options for integration
These are the main options for OpenSSL integration:
- OpenSSL 3.x (Provider): An OpenSSL Provider implementation that translates to PKCS#11. Recommended for modern usecases.
- OpenSSL 1.x (Engine): An OpenSSL Engine implementation that translates to PKCS#11. Use if you only have OpenSSL 1.x, or if your software integration does not yet support the newer provider-based mechanism.
- OpenSSL 1.x (Engine) on Windows: Same as the other engine-based guide, but for Windows.
There may exist other OpenSSL Providers and OpenSSL Engines, but they were not tested.
OpenSSL 1.x is end-of-life since September 2023. It does not receive security updates! Therefore, we highly recommend to use OpenSSL 3.x.
A note on PKCS#11
Recall that the OpenSSL Engine or Provider simply translates to PKCS#11. The plugin teaches OpenSSL how to talk to a PKCS#11 library. It is only a middleware layer. This means:
- The Primus PKCS#11 Provider needs to be configured before the OpenSSL integration.
- For key management (generating keys, exporting certificates, etc.),
it is recommended to use "native" PKCS#11 tools like
pkcs11-toolorp11toolinstead of using OpenSSL. See the examples for how to use these tools.
The second point is because this has fewer layers of indirection. Using OpenSSL is appropriate for integrating applications that do not speak PKCS#11 but that do speak OpenSSL (like Apache or nginx). For manual key management and for applications that speak PKCS#11, using PKCS#11 directly is generally preferred.