Managing Fortanix Data Security Manager Keys With OpenSSL and PKCS#11 Tool

  • Updated on Mar 12, 2025
  • Published on Jun 26, 2024
  • 4 minute(s) read

1.0 Preparing to Use OpenSSL with Fortanix Data Security Manager

To use Fortanix-Data-Security-Manager (DSM) from OpenSSL, you will need to have the following software installed:

  • OpenSSL

  • The OpenSSL PKCS#11 engine. On Debian-based Linux distributions (including Ubuntu), you can install it with sudo apt install libengine-pkcs11-openssl. On CentOS, RHEL, or Fedora, you can install it with yum install engine_pkcs11 if you have the EPEL repository available.

  • The Fortanix DSM PKCS11 library is available here.

  • pkcs11-tool, a utility distributed with the OpenSC smart card library.

  • The version of the PKCS#11 engine library to use when using OpenSSL 3.0 is libp11-0.4.12

  • The path of the PKCS11 engine library (value of dynamic_path in .conf file) when using OpenSSL 3.0 is dynamic_path = /usr/ssl/lib64/engines-3/pkcs11.so

The following sections assume that the $PKCS11_LIBRARY environment variable is set to the location of the Fortanix PKCS11 library (e.g. /usr/lib/x86_64-linux-gnu/pkcs11/fortanix-sdkms-pkcs11.so).

You will need an application in the Fortanix DSM web interface to use with the keys you create. If you don’t yet have an application, create one now.

Create an OpenSSL configuration file openssl-fortanix-sdkms.cnf based on the following template:

openssl_conf = openssl_def

[openssl_def]
engines = engine_section

[req]
distinguished_name = req_distinguished_name

[req_distinguished_name]
# empty.

[engine_section]
pkcs11 = pkcs11_section

[pkcs11_section]
engine_id = pkcs11
dynamic_path = /usr/lib/engines/engine_pkcs11.so
MODULE_PATH = /opt/fortanix/pkcs11/fortanix_pkcs11.so
PIN = <API key>
init = 0

Make the following changes to the template:

  • Replace <API key> with the API key for your application, which you can retrieve from the applications page in the web interface.

  • Update MODULE_PATH to reflect where you have installed the Fortanix PKCS11 library.

  • Set the OPENSSL_CONF environment variable to point to this file.

2.0 Generating a TLS Key and Self-Signed Certificate

This flow can be used to generate a self-signed certificate for testing. Self-signed certificates will not be trusted by clients and should only be used for testing purposes. For production applications, you will want to use the “importing a CA-issued certificate” procedure described below.

Run the following command to generate an RSA key in Fortanix DSM. Replace <API key> with the key obtained from the web interface.

pkcs11-tool --module $PKCS11_LIBRARY --login --pin <API key> -k --id `uuidgen | tr -d -` --label "Self-signed certificate test key" --key-type rsa:2048

Run the following command to generate a self-signed certificate for the new key. You may change the subject of the certificate to suit your needs. Replace  with the ID output in the previous step.

openssl req -engine pkcs11 -keyform engine -new -key 1:<ID> -nodes -days 365 -x509 -sha256 -out test.pem -subj "/CN=test.example.com"

Optionally, you can run the following commands to store the certificate in Fortanix DSM. Replace  with the ID that was output in the key generation step.

openssl x509 -inform pem -outform der -in test.pem -out test.der
pkcs11-tool --module $PKCS11_LIBRARY --login --pin <API key> --write-object test.der --type cert --id <ID> --label "Self-signed certificate test key"

3.0 Generating a TLS Key and Importing a CA Issued Certificate

Run the following command to generate an RSA key in Fortanix DSM. Replace  with the key obtained from the web interface.

pkcs11-tool --module $PKCS11_LIBRARY --login --pin <API key> -k --id `uuidgen | tr -d -` --label "Test key" --key-type rsa:2048

Generate a certificate signing request (CSR) using the following command. Replace  with the ID output in the previous step.

openssl req -engine pkcs11 -keyform engine -new -key 1:<ID> -nodes -sha256 -out test_csr.pem -subj "/CN=test.example.com"

Provide this CSR to your certificate authority (CA). If you need to specify extensions in the request, you can add them to the configuration file.

When you receive the certificate from the CA, you can import it to Fortanix DSM using the following commands. This assumes the certificate is in PEM format in the file cert.pem. Replace  wit the ID that was output by the key generation command.

openssl x509 -inform pem -outform der -in cert.pem -out cert.der
pkcs11-tool --module $PKCS11_LIBRARY --login --pin <API key> --write-object cert.der --type cert --id <ID> --label "Test key"

4.0 Importing a TLS Key and Certificate

If you already have a key and certificate that you wish to use with Fortanix DSM, you can do so. Note that because the key is not generated inside Fortanix DSM, it is possible that copies of the key are stored somewhere. For the best security, use one of the flows above that generates the key within Fortanix DSM.

Assuming you have the private key in a file key.pem, and the certificate in a file cert.pem, you can use the following commands to import the key and certificate to Fortanix DSM . In the last command, replace  with the ID output in the second-to-last command.

openssl x509 -inform pem -outform der -in cert.pem -out cert.der
openssl rsa -inform pem -outform der -in key.pem -out key.der
pkcs11-tool --module $PKCS11_LIBRARY --login --pin <API key> --write-object key.der --type privkey --id `uuidgen | tr -d -` --label "Imported key"
pkcs11-tool --module $PKCS11_LIBRARY --login --pin <API key> --write-object cert.der --type cert --id <ID> --label "Imported key"

When you have completed the import process, you should securely erase the key.pem and key.der files.

5.0 Listing PKCS#11 Objects

You can list the objects available through the PKCS11 library with the following command:

pkcs11-tool --module $PKCS11_LIBRARY --login --pin <API key> -O

Related articles