--- title: "PKCS#11 Library" slug: "fortanix-dsm-clients-pkcs11-library" updated: 2026-07-24T16:28:14Z published: 2026-07-24T16:28:14Z canonical: "support.fortanix.com/fortanix-dsm-clients-pkcs11-library" --- > ## Documentation Index > Fetch the complete documentation index at: https://support.fortanix.com/llms.txt > Use this file to discover all available pages before exploring further. # PKCS#11 Library ## 1.0 Introduction This article provides an overview of the **Fortanix-Data-Security-Manager (DSM) PKCS#11 library**, including its features, supported operations, and platform compatibility. ## 2.0 Download Download the Fortanix Data Security Manager (DSM) PKCS#11 library for all platforms [*here*](https://fortanix.zendesk.com/hc/en-us/sections/4408769080724-PKCS-11). ## 3.0 Operating System (OS) Compatibility *For information on the PKCS#11 client OS compatibility matrix, refer to* [*Compatibility Matrix*](/v1/docs/clients-compatibility-matrix)*.* ## 4.0 Supported Features | **OPERATIONS** | **ALGORITHM** | **KEY SIZE, CURVE,** **PARAMETER SET,** **OR MODE** | | --- | --- | --- | | **Create or Import** | - AES, DES, DES3 as HEX - EC, RSA as PEM - Cert - Pfx - Secret - ML-DSA | Supported key sizes, curves, or parameter sets: - **AES** - 128,192, or 256 bits - **DES** - 56 bits - **DES3** - 112 or 168 bits - **RSA** - between 1024 and 8192 bits - **EC** - SecP192K1, SecP224K1, SecP256K1, NistP192, NistP224, NistP256, NistP384, NistP521, Gost256A, Ed25519, X25519, X448 - **DSA** - - When `key_size` = 2048, the allowed values are 224 or 256 bits. - When `key_size` = 3072, the allowed value is 256 bits. - **HMAC** - between 112 and 8192 bits - **ML-DSA** - CKP_ML_DSA_44, CKP_ML_DSA_65, and CKP_ML_DSA_87. | | **Encrypt or Decrypt** | AES, DES, DES3, RSA | Supported modes: - **AES** - CBC, CBC (no padding), CFB, GCM, GCM (no padding), OFB - **DES**, **DES3** - ECB, CBC, CBC (no padding) - **RSA** - CKM_RSA_PKCS, CKM_SHA1_RSA_PKCS, CKM_SHA224_RSA_PKCS, CKM_SHA256_RSA_PKCS, CKM_SHA384_RSA_PKCS, CKM_SHA512_RSA_PKCS | | **Sign or Verify** | EC, RSA, ML-DSA | Supported modes: - **RSA** - PKCS#1 v1.5, OAEP, OAEPPADDING, PSS - **With hash algorithms (sign/verify)**: CKM_ECDSA_SHA224, CKM_ECDSA_SHA256, CKM_ECDSA_SHA384, CKM_ECDSA_SHA512, CKM_RSA_PKCS_OAEP, CKM_RSA_PKCS_PSS, CKM_SHA1_RSA_PKCS_PSS, CKM_SHA224_RSA_PKCS_PSS, CKM_SHA256_RSA_PKCS_PSS, CKM_SHA384_RSA_PKCS_PSS, CKM_SHA512_RSA_PKCS_PSS - **ML-DSA** - **CKM_ML_DSA** - Input data should be plain [unhashed]. - Has an optional parameter CK_SIGN_ADDITIONAL_CONTEXT - C_Verify - Single-part operations only - **CKM_HASH_ML_DSA** - Input data should be hashed. - Has a required parameter CK_HASH_SIGN_ADDITIONAL_CONTEXT - Only SHA-256 [CKM_SHA256] and SHA-512 [CKM_SHA512] Hash algorithms are supported. - C_Sign - Single-part operations only - C_Verify - Single-part operations only - **CKM_HASH_ML_DSA_** - Input data should be plain [unhashed] - PKCS#11 will do hashing internally and send the hashed data to Fortanix DSM. - Has an optional parameter CK_SIGN_ADDITIONAL_CONTEXT - Only SHA-256 [CKM_HASH_ML_DSA_SHA256] and SHA-512 [CKM_HASH_ML_DSA_SHA512] Hash algorithms are supported. | | **Multipart Encrypt or Multipart Decrypt** | AES | Supported modes: CBC, CBCNOPAD, CTR, and GCM | | **Message Digest** | | Supported hash algorithms: SHA1, SHA256, SHA384, and SHA512, SHA3_224, SHA3_256, SHA3_384, SHA3_512 | | **Wrap Key** | AES, DES, HMAC, RSA, EC | Symmetric keys may be wrapped with symmetric or asymmetric keys. Asymmetric keys may be wrapped with symmetric keys. But wrapping an asymmetric key with another asymmetric key is not supported. | | **Derive Key** | AES, DES, DES3 | Supported key sizes or curves: - **AES** - 128,192, or 256 bits - **DES** - 56 bits - **DES3** - 112 or 168 bits | | **Agree Key** | AES, EC | Supported key sizes or curves: - **AES** - 128,192, or 256 bits - **EC** - SecP192K1, SecP224K1, SecP256K1, NistP192, NistP224, NistP256, NistP384, NistP521 | | **Export Key** | AES, DES, DES3, RSA, EC, HMAC | Supported key sizes or curves: - **AES** and **ARIA** - 128,192, or 256 bits - **DES** - 56 bits - **DES3** - 112 or 168 bits - **HMAC** - between 1024 and 8192 bits - **RSA -** between 1024 and 8192 bits - **EC** - SecP192K1, SecP224K1, SecP256K1, NistP192, NistP224, NistP256, NistP384, NistP521 - **HMAC** - between 1024 and 8192 bits | ## 5.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 the PKCS#11 library is `C:\Program Files\Fortanix\KmsClient\FortanixKmsPkcs11.dll`. *For information on Apache HTTPD TLS and NGINX TLS, refer to* [*Fortanix DSM for NGINX and Apache TLS Keys.*](/v1/docs/using-fortanix-data-security-manager-for-nginx-and-apache-tls-keys) *For information on MariaDB encryption, refer to* [*Fortanix DSM for MariaDB Encryption at Rest.*](/v1/docs/using-fortanix-data-security-manager-for-mariadb-encryption-at-rest) ## 6.0 Usage You can verify that the Fortanix DSM PKCS#11 library is working using the `pkcs11-tool` utility, which is distributed along with the OpenSC smart card library at the [*GitHub official documentation*](https://github.com/OpenSC/OpenSC)*.* ```bash pkcs11-tool --module --show-info ``` The expected output: ```bash Cryptoki version 3.0 Manufacturer     Fortanix Library          Fortanix Data Security Manager PKCS11 Library (ver 0.3) Using slot 0 with a present token (0x1) ``` > [!NOTE] > NOTE > > `Cryptoki` version numbers may differ. 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. *For information on building applications using this PKCS#11 library, refer to* [*User Authentication*](/v1/docs/user-authentication)*.* *For information on configuring legacy applications with a PKCS#11 interface to use Fortanix DSM, refer to* [*Managing Fortanix DSM Keys with OpenSSL and PKCS#11 Tool*](/v1/docs/managing-fortanix-data-security-manager-keys-with-openssl-and-pkcs11-tool)*.* ### 6.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 containing 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] > 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: > > ```bash > FortanixKmsClientConfig.exe machine --api-key > ``` > > Example: > > ```bash > FortanixKmsClientConfig.exe machine --api-key FEL/ME...j+bt7 > ``` > > *For setting the API endpoint in Windows, refer to* [*Section 6.1.1: Configuration File Format*](/v1/docs/clients-pkcs11-library#611-configuration-file-format)*.* #### 6.1.1 Configuration File Format The configuration (config) file can contain just the API key on a single line, or it may include additional parameters as shown below: ```bash api_key = "FEL/ME...j+bt7" api_endpoint = "" or "" # default is "https://apps.smartkey.io" proxy = "http://proxy.corp.example.com:" 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 = 90000 h2_keep_alive_interval_millis = 30000 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" check_server_cert_revocation = false [log] file = "/path/to/log/file" #For Windows, "C:/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 do not want to configure logging, you can omit the entire `[log]` section. > [!NOTE] > NOTE > > For Windows, you need to provide the API endpoint using the Fortanix configuration tool. > > To configure the API endpoint, use the following command: > > ```bash > FortanixKmsClientConfig.exe machine --api-endpoint > ``` > > Example: > > ```bash > FortanixKmsClientConfig.exe machine --api-endpoint https://eu.smartkey.io > ``` - `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. - If you need a web proxy to access your Fortanix DSM endpoint, you can optionally configure it using one of the following methods: - Specify the `proxy` parameter in the configuration file. - Set the `FORTANIX_PROXY` environment variable. - 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* [*Fortanix DSM Key for Generating Certificates*](/v1/docs/generating-certificates-using-a-fortanix-data-security-manager-key)*.* - `cert_file` and `key_file` are supported on both Linux and Windows platforms. 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: ```bash api_endpoint="" cert_file="/path/to/cert-file/.crt" key_file="/path/to/key-file/.pem" exact_key_ops=true app_id="" [log] file="/path/to/log-file/.log" ``` 2. Run the following command to export the environment variable `FORTANIX_PKCS11_CONFIG_PATH` using the config file created in *Step 1*: ```bash export FORTANIX_PKCS11_CONFIG_PATH=/path/to/conf-file/p11.conf ``` 3. Run the following CLI command to generate an RSA key pair: Example: ```bash pkcs11-tool --module "/opt/fortanix/pkcs11/fortanix_pkcs11.so" --login --pin 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: ```bash api_endpoint="" cert_file="/path/to/cert-file/.crt" key_file="/path/to/key-file/.pem" exact_key_ops=true password="" app_id="" [log] file="/path/to/log-file/.log" ``` 2. Run the following CLI command to generate an RSA key pair: Example: ```bash 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 `90000`, which is 90 secs. - `h2_keep_alive_interval_millis` allows users to configure the interval, in milliseconds, between successive HTTP/2 keep-alive PING frames sent to the DSM/proxy. These PINGs are used to verify that the connection used for streaming incoming and outgoing requests is still alive. To configure this parameter, set `h2_keep_alive_interval_millis = xxxx` in the configuration file, where `xxxx` is the interval in milliseconds. The default value is `30000` milliseconds (30 seconds). Alternatively, you can set the `FORTANIX_PKCS11_H2_KEEP_ALIVE_INTERVAL_MILLIS` environment variable. When specified, this environment variable takes precedence over the `h2_keep_alive_interval_millis` configuration parameter. If an ACK is not received within the fixed timeout of 5 seconds, the connection is considered unavailable, terminated, and removed from the connection pool. > [!NOTE] > NOTE > > This feature is effective only when the client host and the middleware successfully negotiate an HTTP/2 connection during the TLS ALPN handshake. - `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: ```bash 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] > NOTE > > - If 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. Add the following parameter to the configuration file to enable it: ```bash add_key_ops_override = "EXPORT" ``` Alternatively, you can set the following environment variable: ```bash export FORTANIX_PKCS11_ADD_KEY_OPS_OVERRIDE="EXPORT" ``` > [!NOTE] > NOTE > > - If both the configuration file parameter and the environment variable for `add_key_ops_override` are set, the environment variable takes precedence. > - If the cryptographic policy on the Fortanix DSM account disallows the `EXPORT` operation, the key creation request in PKCS#11 results in the error: `Some requested operations (EXPORT) is not allowed by policy`. - The `check_server_cert_revocation` parameter enables revocation status verification of the Fortanix DSM server certificate chain. The parameter is **optional**, with a default value set to `false`. To enable certificate revocation checking, add the following to the PKCS#11 configuration file: ```bash check_server_cert_revocation = true ``` Alternatively, certificate revocation checking can be enabled using the following environment variable: ```bash export FORTANIX_PKCS11_CERT_REVOCATION_CHECK_ENABLED=true ``` > [!NOTE] > NOTE > > - Server certificate revocation check details are available when the log level is set to `debug`. > - If both the configuration file parameter and the environment variable are set, the configuration file value takes precedence. - `oracle_tde_cache_config`, enables prefetching of heartbeats in Oracle TDE (optional) by adding the following in the config file: ```bash 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: ```bash [oracle_tde_cache_config] cache_size = 100 request_timeout = 2000 ``` Where, - `cache_size`: Refers to the number of heartbeats that will be prefetched and stored. By default, its value is`60` (This may change). Therefore, 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` to`0` will throw an error. - `request_timeout`*:* Refers to 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 is`1.5`seconds. The `request_timeout` can be set in the following ways: ```bash 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* [*Fortanix DSM with Oracle TDE*](/v1/docs/fortanix-using-fortanix-data-security-manager-with-oracle-tde)*.* #### 6.1.2 Set Client Config API Value 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`. ### 6.2 Logging By default, the PKCS#11 library logs information as follows: - **Linux:** Logs are written to syslog, which is located at: - Ubuntu: `/var/log/syslog` - CentOS: `/var/log/messages` - **Windows:** Logs are written to the file located at `APPDATA%\Roaming\Fortanix\KmsClient\Pkcs11Log.txt`. 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: ```bash api_key = "FEL/ME...j+bt7" api_endpoint = "" or "" [log]     file = "/path/to/log/file" #For Windows, "C:/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 detail 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] > NOTE > > Windows currently does not support custom log levels. #### 6.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] > 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: ```bash [log] file_size_kb=1024 max_files=5       ``` ### 6.3 Using OAuth with PKCS#11 Library The following requirements must be satisfied 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: ```bash api_endpoint = "" or "" 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: ```bash [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. ### 6.4 Supported Functions and Mechanisms *For the list of all functions and mechanisms supported in the PKCS#11 library, refer to* [*PKCS#11 Supported Functions and Mechanisms*](/v1/docs/pkcs11-supported-functions-and-mechanisms)*.* ### 6.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 environment variable `FORTANIX_PROXY` . In Windows, use the following command to set the proxy: ```bash FortanixKmsClientConfig.exe machine --proxy ``` Example: ```bash FortanixKmsClientConfig.exe machine --proxy http://proxy.com:3128 ``` ### 6.6 Login Issues A login failure may be caused by several issues. Perform the following steps to troubleshoot: 1. Check if the API Key being used is correct. 2. 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. 3. 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. ## 7.0 References *For more information on the PKCS#11 client configuration options, refer to* [*Account Client Configurations*](/v1/docs/users-guide-account-client-configurations)*.* ## 8.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`. ```bash alias pkcs11-tool-dsm="pkcs11-tool --module /opt/fortanix/pkcs11/fortanix_pkcs11.so --login --pin file:///etc/fortanix/pkcs11.conf" ``` > [!NOTE] > NOTE > > It is not recommended to store the `APIKey` in an alias. - Generate an RSA key pair. ```bash 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: ```bash 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. ```bash pkcs11-tool-dsm --keygen --label AEStestKey --id 02 --key-type AES:32 ``` - List the available keys. ```bash pkcs11-tool-dsm --list-objects ``` - Sign the file (for example, `input.txt`) using the RSA key (created in the above step) `id 01`. ```bash 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`. ```bash 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). ```bash 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`. ```bash pkcs11-tool-dsm --decrypt --id 02 --mechanism AES-CBC-PAD --iv 50a45ef9295650a45ef9295650a45ef9 --input-file data.enc --output-file output.txt ``` ## 9.0 Troubleshooting The following table describes the possible reasons for errors and exceptions and provides information about resolving them. | **Problem** | **Resolution** | | --- | --- | | Issues while opening the HSM wallet | Ensure the following to troubleshoot: - The `sqlnet.ora` file you edited is the one being used by the database. - The directory permissions of the folder where the software wallet is stored is correct such that it is readable and writeable by `oracle` user. - You have only one PKCS11 library under the folder `/opt/oracle/extapi/64/hsm/`. Having multiple libraries under different sub-folders of this folder can cause Oracle to fail to load any library. | | Failing to open HSM wallet (ORA-28353) | Look at the PKCS11 log file to check if C_Login is failing. A failing entry for C_Login will have non-zero status as follows: `2019-06-13T01:31:36.720632089-04:00 - Fortanix C_Login -> 160` | | DB wallet closes automatically while opening from Fortanix DSM. | Remove the quorum approval from the group/account and try again. | | "certificate already in hash table" error in the PKCS11 log `backend error: ProviderError(NativeTlsError (Ssl(ErrorStack([Error { code: 185057381, library: "x509 certificate routines", function: "X509_STORE_add_cert", reason: "cert already in hash table", file: "x509_lu.c", line: 370 }` | Ensure that you remove the duplicate certificates from the local certificate store. `#/etc/pki/ca-trust/source/anchors (Local cert Store) #/usr/bin/update-ca-trust` | | HSM heartbeat Failure error | Look at the PKCS11 log file to find which PKCS11 function is failing. Oracle performs continuous HSM heartbeat checks by performing a crypto operation with a key stored in HSM. To troubleshoot heartbeat check failure, please check the following: - Verify the information is correct as mentioned in the steps for troubleshooting C_Login failure. - Verify that the Oracle TDE master key in Fortanix DSM is enabled and exists. | | PKCS library fails to open the PKCS11 configuration file and uses default configuration. `oracle[14045]: could not read config file /root/.config/fortanix/pkcs11.conf, using default configuration...` | Look for the PKCS11 errors in the log file. For example, `/var/log/mesages` | | API failures from the PKCS#11 service. | Configure the error retry limit by setting `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. For example, `retry_timeout_millis = 6000` sets the retry limit to 6 secs. The default value is `3000`, which is 3 secs. | | When running your application, the system returns a `CKR_GENERAL_ERROR`. This typically occurs when the application lacks the necessary permissions to write to the designated log file, preventing the SDK or API client from recording required operational data. | Ensure that the log file path is correctly defined and that the execution environment has sufficient filesystem permissions. 1. **Update the Configuration** - Define the log file path in your configuration file. Ensure that the `[log]` section is properly configured, as shown below: ```yaml api_endpoint = "" api_key = "YOUR_API_KEY" retry_timeout_millis = 30000 [log] level = "info" file = "/path/to/your/logfile.log" ``` 2. **Verify Filesystem Permissions** - Ensure that the application has write access to the specified log file path. Update file or directory permissions as needed. 3. **Validate the Configuration** - Restart the application after applying the changes. If the log file is successfully created and populated with info-level entries, the issue should be resolved. | | Panic or crash observed in PKCS#11 flow when using OpenSSL provider with PQC algorithms. | Add `pkcs11-module-quirks = no-deinit` in `openssl.cnf` file to avoid the panic or crash: ```bash ... [pkcs11_sect] ... pkcs11-module-quirks = no-deinit <<==== ... ``` | ## 10.0 Changelog *For information on the PKCS#11 client changelog, refer to* [*PKCS#11 Changelog*](https://fortanix.zendesk.com/hc/en-us/articles/4408769594260-PKCS-11-Changelog)*.* Fortanix Data Security Manager (DSM) is the world’s first cloud service secured with Intel® SGX. With Fortanix DSM, you can securely generate, store, and use cryptographic keys and certificates, as well as other secrets such as passwords, API keys, tokens, or any blob of data. Your business-critical applications and containers can integrate with Fortanix DSM using legacy cryptographic interfaces (PKCS#11, CNG, and JCE) or using the native Fortanix DSM RESTful interface. ## Related - [PKCS#11 Supported Functions and Mechanisms](/fortanix-dsm-clients-pkcs11-supported-functions-and-mechanisms.md) - [Authentication](/dsm-authentication.md) - [Security Controls for Fortanix DSM Applications](/security-controls-for-fortanix-data-security-manager-applications.md) - [Managing Fortanix DSM Keys with OpenSSL and PKCS#11 Tool](/managing-fortanix-dsm-keys-with-openssl-and-pkcs11-tool.md)