Configuring OpenSSL to use the eHSM or MIRkey Hardware Security Modules

Last updated December 1, 2020

This guide will show you how to configure OpenSSL to use the eHSM or MIRkey hardware modules for cryptographic operations.

  1. Download and install the eHSM shared library for your platform here:

    Important: Always verify the signature of the downloaded files

  2. Initialize and configure your device using the quick start guide instructions.

  3. Install libp11 for your platform.

  4. Create an OpenSSL engine config file, using the template below as a starting point:

     openssl_conf = openssl_init
     engines = engine_section
     pkcs11 = pkcs11_section
     engine_id = pkcs11
     # dynamic_path is not required if you have installed
     # the appropriate pkcs11 engines to your openssl directory
     #dynamic_path =  /opt/local/lib/engines-1.1/libpkcs11.dylib{.so/.dll}
     #path to ehsm.dll/
     MODULE_PATH = /usr/local/lib/libehsm.dylib
     [ req ]
     distinguished_name = req_dn
     string_mask = utf8only
     utf8 = yes
     [ req_dn ]
     # Adjust for your certificate requirements
     commonName =

    Save the file as engine.conf

    Note: To use the default OpenSSL certificate template, integrate engine_section and pkcs11_section into the default openssl.cnf file.

  5. To test the configuration, run the following command:

     OPENSSL_CONF=engine.conf openssl engine -t -c pkcs11

    This should indicate that the engine is available:

     (pkcs11) pkcs11 engine
      [RSA, rsaEncryption, id-ecPublicKey]
          [ available ]
  6. With a working configuration, the following examples illustrate how some common OpenSSL commands work using the configured engine.

Create a test key for these examples using either the ellipticSecure Device Manager, or using pkcs11-tool:

pkcs11-tool --module /usr/local/lib/libehsm.dylib --login\
       --keypairgen --key-type EC:prime256v1 --label "testkey" --usage-sign --id 1

Alternatively, generate an RSA key:

pkcs11-tool --module /usr/local/lib/libehsm.dylib --login\
       --keypairgen --key-type rsa:2048 --label "testrsakey" --usage-sign --id 2

Use the label for the key above, “testkey” or “testrsakey”, in all the following OpenSSL commands.

  • Create a self-signed certificate using OpenSSL:
OPENSSL_CONF=engine.conf openssl req -new -x509 -days 365 -subj '/CN=My Test Key/' -sha256 -config \
    engine.conf -engine pkcs11 -keyform engine -key slot_0-label_testkey \
    -out cert.pem
  • Generate a CSR for the key on the HSM using OpenSSL:
OPENSSL_CONF=engine.conf openssl req -engine pkcs11 -keyform engine -new -key slot_0-label_testkey \
    -nodes -sha256 -out test_csr.pem -subj '/'

When you receive the signed certificate from the CA, you can import it using the ellipticSecure Device Manager or using:

openssl x509 -inform pem -outform der -in cert.pem -out cert.der
pkcs11-tool --module /usr/local/lib/libehsm.dylib --login --write-object cert.der --type cert \
   --id 1 --label "testkey"

Note that the label and id of the imported certificate needs to match the key for many applications to work correctly.

Subscribe to receive updates

* indicates required