Use the OpenSSL dynamic engine

Updated at:

The OpenSSL dynamic engine lets you offload RSA private key operations to a hardware security module (HSM), keeping private keys inside the hardware at all times. This guide walks you through loading the engine and performing RSA encryption and decryption.

Prerequisites

Before you begin, ensure that you have:

  • An initialized HSM instance with a crypto user (CU) created. See Quick Start.

  • The HSM client (hsm_proxy) running. See Start the HSM client (hsm_proxy).

  • OpenSSL with dynamic engine loading support. To verify, run:

    Note

    Only OpenSSL version 1.0.2 is supported.

    openssl engine -c

    If dynamic engine loading is supported, the output includes:

    (dynamic) Dynamic engine loading support

RSA encryption and decryption

Step 1: Set environment variables

Export the library path and CU credentials. Replace <HSMusername> with the CU username and <password> with the CU password.

export LD_LIBRARY_PATH=/opt/hsm/lib/:$LD_LIBRARY_PATH
export n3fips_password=<HSMusername>:<password>

Step 2: Enter interactive mode

openssl

Step 3: Load the dynamic engine

engine dynamic -pre SO_PATH:/opt/hsm/lib/libhsm_openssl.so -pre ID:hsm_openssl -pre LIST_ADD:1 -pre LOAD

A successful response looks like:

Loaded: (hsm_openssl) Cavium hardware engine support

Step 4: Generate an RSA key pair

genrsa -engine hsm_openssl

The engine generates an RSA key inside the HSM and returns a pseudo-PEM file encoding the key handle. Save this output to a file — for example, /root/openssl/priv.key.

The pseudo-PEM output looks like a standard RSA private key block, but contains only a reference to the HSM-stored key:

-----BEGIN RSA PRIVATE KEY-----
****IQIBAAKCAQEAp2R756S3q1/Aa0htOSXovkakVI3ePqkMY4I/AM7j6ZO4lf1b
l58v0zUqk8c9Eknf8VclGrMz8vqEOMWWXUM6xc4Jq6HRhBbp/SdqTlSW+6WjYcG3
nMP5PxBIuWLazjS7Mte3n3NSK+qS2jIeUdhr+OPhCdeQfxsDbc9CTz97NNDnoARR
64nZ/mMTBHXW5dkbgOmTE3plCqB0NctTwXgF3C6z+6/vASJEdXseFV7GS5vATNf4
i7uEkIIx0791Ped0+3yoBZ31XuAQKcspEab+z3cRdvjUb0YluYF00WDu3D/5bBYW
0epo6l1r83EhqeAhOviUqQLwMJoLeUxif8RpNQIDAQABAoIBAQDq/Pzu6vz87h8A
AAAAAAAA6vz87ur8/O7q/Pzu6vz87ur8/O7q/Pzu6vz87ur8/O7q/Pzu6vz87ur8
/O7q/Pzu6vz87ur8/O7q/Pzu6vz87ur8/O7q/Pzu6vz87ur8/O7q/Pzu6vz87ur8
/O7q/Pzu6vz87ur8/O7q/Pzu6vz87ur8/O7q/Pzu6vz87ur8/O7q/Pzu6vz87ur8
/O7q/Pzu6vz87ur8/O7q/Pzu6vz87ur8/O7q/Pzu6vz87ur8/O7q/Pzu6vz87ur8
/O7q/Pzu6vz87ur8/O7q/Pzu6vz87ur8/O7q/Pzu6vz87ur8/O7q/Pzu6vz87ur8
/O7q/PzuAgEAAgEAAgEAAgEA****
-----END RSA PRIVATE KEY-----

Step 5: Export the public key

rsa -in /root/openssl/priv.key -pubout -out /root/openssl/pub.pem

Step 6: Encrypt a file

Important

Run this command in non-interactive mode (outside the openssl shell).

In this example, /root/openssl/helloworld.txt contains the text hello world!.

openssl rsautl -encrypt -inkey /root/openssl/pub.pem -pubin -in /root/openssl/helloworld.txt -out /root/openssl/helloworld.txt.enc

Step 7: Decrypt a file

Important

Run this command in interactive mode (inside the openssl shell) with the dynamic engine already loaded (steps 2–3).

openssl rsautl -decrypt -inkey /root/openssl/priv.key -in /root/openssl/helloworld.txt.enc -out /root/openssl/helloworld.txt.dec

The decrypted content is written to /root/openssl/helloworld.txt.dec.