Managing SmartKey Keys With OpenSSL and pkcs11-tool

Updated: May 31, 2017

Preparing to use OpenSSL with SmartKey

To use SmartKey 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 SmartKey PKCS11 library, available here.
  • pkcs11-tool, a utility distributed with the OpenSC smart card library.

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

You will need an application in the SmartKey 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.

  • 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 SmartKey PKCS11 library.
  • Set the OPENSSL_CONF environment variable to point to this file.

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 = /usr/lib/x86_64-linux-gnu/pkcs11/fortanix-sdkms-pkcs11.so
PIN = <API key>
init = 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 SmartKey. 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 <ID> 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 SmartKey. Replace <ID> 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"

Generating a TLS key and importing a CA-issued certificate

Run the following command to generate an RSA key in SmartKey. 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 "Test key" --key-type rsa:2048

Generate a certificate signing request (CSR) using the following command. Replace <ID> 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 SmartKey using the following commands. This assumes the certificate is in PEM format in the file cert.pem. Replace <ID> wit hthe ID that was ouptut 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"

Importing a TLS key and certificate

If you already have a key and certificate that you wish to use with SmartKey, you can do so. Note that because the key is not generated inside SmartKey, 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 SmartKey.

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 SmartKey. In the last command, replace <ID> 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.

Listing PKCS11 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