Clients: PKCS#11 Library

1.0 Download

The Fortanix-Data-Security-Manager (DSM) PKCS#11 library for all platforms can be downloaded here.

2.0 Operating System (OS) Compatibility Matrix

For details on the PKCS#11 client OS compatibility matrix, refer to Clients: Compatibility Matrix.

3.0 Supported Features

4.0 Installation

The RPM and DEB installer copies the Fortanix DSM PKCS#11 shared object file (also called library or module) to /opt/fortanix/pkcs11/fortanix_pkcs11.so.

The Windows installer installs the PKCS#11 Library, as well as the Fortanix CNG and EKM providers. The default installation location of PKCS#11 library is C:\Windows\Program Files\Fortanix\KmsClient\FortanixKmsPkcs11.dll.

For information on Apache HTTPD TLS and NGINX TLS, refer to Using Fortanix Data Security Manager for NGINX and Apache TLS Keys.

For information on MariaDB encryption, refer to Using Fortanix Data Security Manager for MariaDB Encryption at Rest.

5.0 Usage

You can verify that you can use the Fortanix DSM PKCS#11 library using the pkcs11-tool utility, which is distributed along with the OpenSC smart card library at https://github.com/OpenSC/OpenSC.

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

The expected output is:

Cryptoki version 3.0
Manufacturer     Fortanix
Library          Fortanix Data Security Manager PKCS11 Library (ver 0.3)
Using slot 0 with a present token (0x1)

Applications use the Fortanix DSM PKCS#11 library to interact with Fortanix DSM 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 keyspace. However, Fortanix DSM 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. Fortanix DSM 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 32 (numbered 0-31) and can be configured through the environment variable FORTANIX_PKCS11_NUM_SLOTS.

Administration of Fortanix DSM 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, 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 Fortanix DSM.

5.1 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:

1. API key (a 164-character string): For example, FEL/ME...j+bt7.

2. file://path-to-configuration-file: The path may be absolute (for example, file:///home/fortanix/pkcs11.cfg) or relative (for example, file://pkcs11.cfg).

3. env:environment-variable-name: The environment variable may contain the API key directly or specify a file, as shown previously.

4. password:PRIVATE_KEY_PASSWORD: The password used to unlock the private key file for key or certificate authentication.

NOTE

For Windows, you may provide the API key using the Fortanix configuration tool instead of providing it during C_Login. To configure the API key, use the following command:

FortanixKmsClientConfig.exe machine --api-key <your api_key>

For example,

FortanixKmsClientConfig.exe machine --api-key FEL/ME...j+bt7

For setting the API endpoint in Windows, refer to the Section 5.1.1: Configuration File Format.

5.1.1 Configuration File Format

The configuration (config) 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 = "" or "" # default is "https://apps.smartkey.io"
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
password = ""   # Use this field only when PKCS#8 PEM client private key is encrypted
app_id = "59be5a1e-8935-4a0a-a272-b0c8512d99f1"

prevent_duplicate_opaque_objects = true
retry_timeout_millis = 3000
max_concurrent_requests_per_slot = 0
exact_key_ops = true
signing_aes_key_as_hmac - false
opaque_objects_are_not_certificates = false
add_key_ops_override = "EXPORT"

[log]
file = "/path/to/log/file"
level = "info" 

[quorum_approval.wait_for_quorum_approval]
enabled = true
poll_interval_secs = 5 
max_wait_for_secs = 100

• The api_key and api_endpoint 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.

  • api_key: This is the API key used for authentication.

  • api_endpoint: This parameter defines the endpoint URL or IP address to which the PKCS#11 client connects. The default endpoint is https://apps.smartkey.io, but it can be customized by specifying a different URL or IP address.

NOTE

For Windows, you need to provide the API endpoint using the Fortanix configuration tool. To configure the API endpoint, use the following command:

FortanixKmsClientConfig.exe machine --api-endpoint <your api_endpoint>

For example,

FortanixKmsClientConfig.exe machine --api-endpoint https://eu.smartkey.io

• By default, the trusted certificates used to verify the connection with the Fortanix DSM 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. For information on generating certificates, refer to Generating Certificates using a Fortanix Data Security Manager key.

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

  If the key_file is password protected, you can use one of the following methods for key or certificate authentication:

  • Provide a password for a password-protected private key file as a command line parameter.

    1. Create a config file (for example, <p11.conf>) using the following configuration values:

       api_endpoint="<API-ENDPOINT>"
       cert_file="/path/to/cert-file/<cert-name>.crt"
       key_file="/path/to/key-file/<pkcs8-key>.pem"
       exact_key_ops=true
       app_id="<APP-ID>"
       [log]
       file="/path/to/log-file/<log-name>.log"

    2. Run the following command to export the environment variable FORTANIX_PKCS11_CONFIG_PATH using the config file created in Step 1:

       export FORTANIX_PKCS11_CONFIG_PATH=/path/to/conf-file/p11.conf

    3. Run the following CLI command to generate an RSA key pair:
       For example:

       pkcs11-tool --module "/opt/fortanix/pkcs11/fortanix_pkcs11.so" --login --pin password:<PRIVATE-KEY-PASSWORD> -I -O

  • Provide a password for a password-protected private key file as part of the config file.

    1. Create a config file (for example, <p11.conf>) using the following configuration values:

       api_endpoint="<API-ENDPOINT>"
       cert_file="/path/to/cert-file/<cert-name>.crt"
       key_file="/path/to/key-file/<pkcs8-key>.pem"
       exact_key_ops=true
       password="<PRIVATE-KEY-PASSWORD>"
       app_id="<APP-ID>"
       [log]
       file="/path/to/log-file/<log-name>.log"

    2. Run the following CLI command to generate an RSA key pair:

       For example:

       pkcs11-tool --module "/opt/fortanix/pkcs11/fortanix_pkcs11.so" --login --pin file:///path/to/conf-file/p11.conf --keypairgen --label RSAtestKey --id 01 --key-type RSA:4096 -I -O

• 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 Fortanix DSM 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.

• poll_interval_secs is the time gap between each quorum status check-in. The polling interval must not surpass 600 seconds (equivalent to 10 minutes).

• max_wait_for_secs is the maximum duration for the client library to await a response from the server in seconds.

• The PKCS#11 library additionally supports the following:

  • To prevent creating duplicate opaque objects, set prevent_duplicate_opaque_objects = true in the config file. This would skip creating new Opaque objects if there is an existing Opaque object with the same CKA_LABEL. The default value for prevent_duplicate_opaque_object is false .

  • To configure the error retry limit, set retry_timeout_millis = xxxx in the config file. Where xxxx is the value of time in milliseconds. This is the maximum duration for which the PKCS#11 library will do any number of retries in case of API failures from the service. For example, retry_timeout_millis = 6000 sets the retry limit to 6 secs. The default value is 3000, which is 3 secs.

  • max_concurrent_requests_per_slot, which will limit the number of concurrent HTTP requests a client can make to Fortanix DSM per slot, which effectively limits the number of concurrent API calls a client can make. This can be used to prevent a client from consuming too many resources.
    If unset, the value will be inherited.  The default value is 0, which means to impose no limit.  Setting a value of 0 can override a limit imposed elsewhere.  For example, if the config file specifies a limit of 100, and the environment variable is set to 0, there will be no limit.

  • exact_key_ops, which will allow the user to explicitly specify the key operations when creating a key instead of the PKCS#11 having to specify the default key operations. For example, when creating an AES key using C_GenerateKey in “exact key ops” mode, the user needs to explicitly specify the key operations in the attribute template, as follows:

    CK_ULONG len = 16; // 128-bit AES key
    
    CK_ATTRIBUTE aesKeyTemplate[] = {
        {CKA_VALUE_LEN, &len, sizeof(len)},
        {CKA_ENCRYPT, &true, sizeof(true)},
        {CKA_DECRYPT, &true, sizeof(true)},
        {CKA_WRAP, &true, sizeof(true)},
        {CKA_UNWRAP, &true, sizeof(true)},
        {CKA_DERIVE, &true, sizeof(true)},
        {CKA_EXTRACTABLE, &true, sizeof(true)}
    };

    The key created using the template above will contain exactly the key ops that the user specified in the template.

    NOTE

    • If, for instance, the user forgot to specify the CKA_ENCRYPT attribute in the template, the resulting key in Fortanix DSM would not have the ENCRYPT permission.

    • If the user does not specify any key operations (apart from APPMANAGEABLE, which corresponds to the PKCS #11 attributes CKA_MODIFIABLE or CKA_DESTROYABLE), then the PKCS #11 client assigns the following default key operations.

      • For RSA keys, the client assigns SIGN and VERIFY

      • For non-RSA keys, the client assigns the usual defaults such as ENCRYPT, DECRYPT, WRAPKEY, UNWRAPKEY, and so on minus APPMANAGEABLE

      • For non-key objects, we assign EXPORT.

• The add_key_ops_override parameter ensures that the EXPORT key operation is always included during the key creation from PKCS#11 by adding  the following in the config file:

  add_key_ops_override = "EXPORT"

  Alternatively, you can set the following environment variable:

  export FORTANIX_PKCS11_ADD_KEY_OPS_OVERRIDE="EXPORT"

  NOTE

  • If both the configuration file parameter and the environment variable for add_key_ops_override are set, the environment variable will take precedence.

  • If the cryptographic policy on the Fortanix DSM account disallows the EXPORT operation, the key creation request in PKCS#11 will result in the error: Some requested operations (EXPORT) is not allowed by policy.

• oracle_tde_cache_config, enables prefetching of heartbeats in Oracle TDE (optional) by adding the following in the config file:

  oracle_tde_cache_config = {}

  This is a table in toml representation and the above format expresses it as an inline table.

  Adding oracle_tde_cache_config is the simplest way of enabling the feature and the default values are used for all configurations.  It is also possible to change the values of some configurations as shown below:

  [oracle_tde_cache_config] 
  cache_size = 100 
  request_timeout = 2000
  

  where,

  • cache_size: This is the number of heartbeats that will be prefetched and stored. By default, its value is60 (this may change). So, a value of 60 means that 60 heartbeats will always be available for use, in case of a connectivity loss. Since by default, a heartbeat is fired every 3 seconds, 60 cache_size should provide a backup for 3 minutes. Setting cache_size to0 will throw an error.

  • request_timeout: The immediate heartbeat request is served from the cache but a prefetch request is always made to keep the prefetch cache full. But this prefetch request happens within the actual heartbeat request and will block it. It may take longer in case of network connectivity issues and may trigger heartbeat failure. So, you need to ensure this request is abandoned if it is taking extra time. request_timeout tells how long this prefetch request is allowed to block. By default, it is1.5seconds.
    The request_timeout can be set in the following ways:

    request_timeout = 2000 # this is in milliseconds, that is 2 seconds
    
    request_timeout = { secs = 1, nanos = 1} # 1 second + 1 nano second 

    For more information on enabling prefetching of heartbeats, refer to Integrating Oracle TDE with Fortanix DSM.

5.1.2 Set the Value of the Client Config API

The client config API for fake_rsa_x9_31_keygen_support, signing_aes_key_as_hmac, exact_key_ops, prevent_duplicate_opaque_objects, opaque_objects_are_not_certificates, retry_timeout_millis, max_concurrent_requests_per_slot, and exact_key_ops can be set in three ways. In decreasing order of precedence, they are as follows:

• Using environment variables

• An option in the configuration file

• The Client Configuration tab on the Account Settings page in the Fortanix DSM UI uses the Client Configuration API to add a field to Pkcs11ClientConfig.  

5.2 Logging

By default, the PKCS#11 library logs information as follows:

• Linux: Logs are written to syslog, which is typically located at,

  • Ubuntu: /var/log/syslog

  • CentOS: /var/log/messages

• Windows: Logs are written to the file located at %APPDATA%\Fortanix\KmsClient\pkcs11.log.

These logs capture all function calls made to the PKCS#11 library, including their return values. This is particularly helpful for debugging and troubleshooting.

The log file location can also be configured for PKCS#11 clients by adding the following to your client configuration file:

api_key = "FEL/ME...j+bt7"
api_endpoint = "<ENDPOINT URL>" or "<ENDPOINT IP>"

[log]     
file = "/path/to/log/file"
level = "info" 

• [log]: The [log] section allows configuration of the log file behavior.

  • file: This optional parameter specifies the file path where the logs will be saved.

    • A valid file path must be provided for the file parameter.

    • The directory containing the file must already exist.

    • The process running the PKCS#11 library must have "write" permissions for the specified file.

      If these conditions are not met, the PKCS#11 library will not be able to log appropriately.

  • level: This optional parameter controls the level of details in the logs.

    • To enable additional logging, set the level parameter to debug. Valid values for the log level are error, warn, info, trace, and debug, with the default being info.

    • The log level can also be set using the environment variable FORTANIX_PKCS11_LOG_LEVEL .

      NOTE

      Windows currently does not support custom log levels.

5.2.1 Automatic Log Rotation

By default, logs are rotated when they reach 1MB, and 5 copies of the log are retained.

To configure log rotation, add the following parameters to the log section of your configuration file:

• file_size_kb: Specifies the size limit in kilobytes (KB) for each log file before it is rotated.

• max_files: Defines the maximum number of log files to keep.

  NOTE

  If the max_files limit is reached and a new log file needs to be created, the oldest log file will be deleted to maintain the total number of log files within the specified limit.

In the following example, the log will rotate once it reaches 1MB (1024 KB) and a maximum of 5 log files will be kept:

[log]
file_size_kb=1024
max_files=5      

5.3 Using OAuth with PKCS#11 Library

The following requirements must be satisfied in order to use the OAuth scheme with the PKCS#11 library:

• A configuration file must exist either at the default location /etc/fortanix/pkcs11.conf or the path specified in the environment variable FORTANIX_PKCS11_CONFIG_PATH.

• The configuration file must include the api_key and the following snippet:

api_endpoint = "<ENDPOINT URL>" or "<ENDPOINT IP>"
api_key = "...."

[oauth]
method = "user_credentials"

• When calling C_Login(), the pin must be the base 64 encoded username: password of the user who wants to authorize the app.

• The user authorizing the app must be in exactly one account or the configuration file should list the account id in the oauth section:

[oauth]
method = "user_credentials"
acct_id = "..."

• The user authorizing the app must have a group administrator role in exactly one group. This is because the library would need to know how to specify a default group for the app when granting an OAuth authorization code.

• The app must have OAuth enabled and it must include the following redirect URI in its settings: https://pkcs11-library.invalid. This can be set through the Fortanix DSM frontend on the app object.

5.4 Supported Functions and Mechanisms

For the list of all functions and mechanisms supported in the PKCS#11 library, refer to the article PKCS#11 Supported Functions and Mechanisms.

5.5 Connection Issues

A connection issue between the PKCS#11 library and Fortanix DSM 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:

• Check your network connectivity to ensure that the PKCS#11 library is able to reach Fortanix DSM over TCP port 443.

• Check if the FORTANIX_API_ENDPOINT environment variable is set correctly to point to your Fortanix DSM deployment.

• If you need a web proxy to reach your Fortanix DSM deployment, you can configure it using the env variable FORTANIX_PROXY.

  In Windows, use the following command to set the proxy:

  FortanixKmsClientConfig.exe machine --proxy <proxy URL>

  For example,

  FortanixKmsClientConfig.exe machine --proxy https://proxy.com:3128

5.6 Login Issues

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

• Check if the API Key being used is correct.

• Check if the Fortanix DSM endpoint is set correctly. Fix the FORTANIX_API_ENDPOINT environment variable if API requests are going to an incorrect endpoint.

• Some applications require the PIN for their PKCS#11 library to be limited to a maximum number of characters. The Fortanix DSM 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.

6.0 References

For more details on the PKCS#11 client configuration options, refer to the User's Guide: Client Configurations.

7.0 Useful PKCS#11 Commands

PKCS#11 tool commands help interact with cryptographic tokens and perform various operations. They can list objects, perform cryptographic operations, and manage keys.

Consider the following PKCS#11 commands for your reference:

• Create an alias to include --module and --pin.

  alias pkcs11-tool-dsm="pkcs11-tool --module /opt/fortanix/pkcs11/fortanix_pkcs11.so --login --pin file:///etc/fortanix/pkcs11.conf"

  NOTE

  It is not recommended to store the APIKey in an alias.

• Generate an RSA key pair.

  pkcs11-tool-dsm --keypairgen --label RSAtestKey --id 01 --key-type RSA:4096

  Use the following command if you do not want to use an alias:

  pkcs11-tool --module /opt/fortanix/pkcs11/fortanix_pkcs11.so --login --pin file:///etc/fortanix/pkcs11.conf --keypairgen --label RSAtestKey --id 01 --key-type RSA:4096

• Generate an AES key.

  pkcs11-tool-dsm --keygen --label AEStestKey --id 02 --key-type AES:32

• List the available keys.

  pkcs11-tool-dsm --list-objects

• Sign the file (for example, input.txt) using the RSA key (created in the above step) id 01.

  pkcs11-tool-dsm --sign --id 01 --mechanism SHA256-RSA-PKCS --input-file input.txt --output-file data.sig

• Verify the file (for example, data.sig) using the key id 01.

  pkcs11-tool-dsm --verify --id 01 --mechanism SHA256-RSA-PKCS --input-file input.txt --signature-file data.sig

• Encrypt the file (for example, input.txt) using the key id 02 (created in the above step).

  pkcs11-tool-dsm --encrypt --id 02 --mechanism AES-CBC-PAD --iv 50a45ef9295650a45ef9295650a45ef9 --input-file input.txt --output-file data.enc

• Decrypt the file (for example, data.enc) using the key id 02.

  pkcs11-tool-dsm --decrypt --id 02 --mechanism AES-CBC-PAD --iv 50a45ef9295650a45ef9295650a45ef9 --input-file data.enc --output-file output.txt

8.0 Troubleshooting

The following table describes the possible reasons for errors and exceptions and provides information about resolving them.

9.0 Changelog

For details on the PKCS#11 client changelog, refer to PKCS#11 Changelog.