Configuring OpenSSL to use the eHSM or MIRkey Hardware Security Modules

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: https://ellipticsecure.com/downloads/

   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
       
    [openssl_init]
    engines = engine_section
       
    [engine_section]
    pkcs11 = pkcs11_section
       
    [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/libehsm.so/.dylib
    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 = test.acme.com
   

   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 '/CN=test.acme.com'

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.