PKCS#11 Library

Updated: 10 Dec 2019


The SmartKey™ PKCS#11 library for Linux 64-bit can be downloaded here.


To install, run sudo ./ To uninstall, run sudo ./

The installer copies the SmartKey™ PKCS#11 shared object file (also called library or module) to /opt/fortanix/pkcs11/


You can verify that you can use the SmartKey PKCS#11 library using the pkcs11-tool utility, which is distributed along with the OpenSC smart card library at

pkcs11-tool --module <module path> --show-info

The expected output is:

Cryptoki version 2.40
Manufacturer     Fortanix
Library          SmartKey PKCS#11 Library (ver 0.3)
Using slot 0 with a present token (0x1)

Applications use SmartKey PKCS#11 library to interact with SmartKey for key management and cryptographic operations. The PKCS#11 specification has notions of slots and tokens, which correspond to physical entities in an HSM. Multiple clients or applications connecting to a token on an HSM have equal access to the entire key space. However, SmartKey allows access to several applications simultaneously while guaranteeing strong cryptographic separation of key spaces. This is equivalent to every application having access to its own HSM. SmartKey PKCS#11 library implements this by mapping the application credential to the user PIN, and by having an arbitrarily large number of slots (numbered from 0), with a single token (numbered 1) already initialized. The number of slots defaults to 512 (numbered 0-511) and may be configured through the environment variable FORTANIX_PKCS11_NUM_SLOTS. Administration of SmartKey is done using the web UI and using the REST APIs, so the support for doing it through the PKCS#11 library is disabled. PKCS#11 security officer login is disabled, and will always fail with CKR_PIN_INCORRECT. Similarly, the administrative functions such as C_InitToken, C_InitPIN, and C_SetPIN return errors such as CKR_PIN_INCORRECT or CKR_USER_NOT_LOGGED_IN.

The library can also be used by Java applications using the SunPKCS11 JCE provider. Some examples to build applications using this PKCS#11 library are provided in example code. Please look at our Knowledge Base to learn more about how to configure legacy applications with a PKCS#11 interface to use SmartKey™.

User PIN

When executing C_Login, the API key must be provided as the PIN. Alternatively, the PIN may point to a file to configure additional options. The PIN must have one of the following formats:

  • API key (a 164-character string), for example FEL/ME...j+bt7.
  • file://path-to-configuration-file. The path may be absolute (e.g file:///home/fortanix/pkcs11.cfg) or relative (e.g. file://pkcs11.cfg). See below for the file format.
  • env:environment-variable-name. The environment variable may contain the API key directly or specify a file as shown previously.

Configuration file format

The configuration file may contain just the API key on a single line, or it may contain additional options as follows:

api_key = "FEL/ME...j+bt7"
api_endpoint = "" # default is ""
fake_rsa_x9_31_keygen_support = false # default is false

ca_certs_file = "/path/to/certs.pem" # X.509 PEM CA certificates

cert_file = "/path/to/cert.pem" # X.509 PEM client certificate
key_file = "/path/to/key.pem" # PKCS#8 PEM client private key
app_id = "59be5a1e-8935-4a0a-a272-b0c8512d99f1"

system = true # Unix only, logs to syslog
file = "/path/to/log/file"

Exactly one of api_key and app_id are required; the other fields are optional and may be omitted. For example, if you don’t want to configure logging, you can omit the entire [log] section.

By default, the trusted certificates used to verify the connection with the SmartKey server are provided by the system. Additional trusted certificates may be specified by setting the ca_certs_file configuration option. It must point to a file containing one or more concatenated X.509 certificates in PEM format.

cert_file and key_file are currently only supported on Linux. If provided, the client certificate and key are used to authenticate to the the server. If the app does not have an API key, app_id must be specified.

fake_rsa_x9_31_keygen_support = true allows the PKCS#11 mechanism CKM_RSA_X9_31_KEY_PAIR_GEN to be specified when generating RSA keys, even though SmartKey always uses CKM_RSA_PKCS_KEY_PAIR_GEN. The generated key is fully functional but does not use the X9.31 generation procedure.

Setting the environment variable FORTANIX_PKCS11_FAKE_RSA_X9_31_KEYGEN_SUPPORT also allows this.



By default, our PKCS#11 library writes logs into Syslog on Linux (typically at /var/log/syslog on Ubuntu and /var/log/messages on CentOS) and to the file at %APPDATA%\Fortanix\KmsClient\pkcs11.log on Windows. Logs can also be redirected to another file in the filesystem specified in the configuration file described above. All the function calls made into the PKCS#11 library are logged in the log file along with the return value for these calls. The pkcs11 log file is useful for debugging and troubleshooting. For additional logging, the environment variable FORTANIX_PKCS11_LOG_LEVEL can be set to “debug”.

Connection issues

A connection issue between the PKCS#11 library and SmartKey may cause function calls to fail with the error code CKR_DEVICE_ERROR. This can be observed in the PKCS#11 log file. If that happens, check for the following: - The PKCS#11 library should be able to reach SmartKey over TCP port 443, so the first thing to check is for any obvious network connectivity issues. - If you need a web proxy to reach SmartKey, you can configure it using the environment variable FORTANIX_PROXY

Login issues

A login failure may caused by several issues. Follow the following steps to troubleshoot:

  • Check if the API Key being used is correct.
  • Some applications require the PIN for their PKCS#11 library to be limited to a maximum number of characters. The SmartKey API Key is 165 characters long. If this is the case, store the API Key in an environment variable or a file and create a PIN using the appropriate prefix as explained above.