Use the OpenSSL dynamic engine
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:
NoteOnly OpenSSL version 1.0.2 is supported.
openssl engine -cIf 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
opensslStep 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 LOADA successful response looks like:
Loaded: (hsm_openssl) Cavium hardware engine supportStep 4: Generate an RSA key pair
genrsa -engine hsm_opensslThe 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.pemStep 6: Encrypt a file
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.encStep 7: Decrypt a file
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.decThe decrypted content is written to /root/openssl/helloworld.txt.dec.