DSM Accelerator PKCS#11 Developer Guide

1.0 Overview

Fortanix-Data-Security-Manager (DSM), in conjunction with Fortanix DSM Accelerator, provides a comprehensive application encryption and tokenization service with high throughput and low latency.

Fortanix DSM allows you to securely generate, store, and use cryptographic keys and certificates, as well as secrets, such as passwords, API keys, tokens, or any blob of data. Fortanix DSM can be clustered in geographically dispersed locations and deployed in bare-metal, on-premises, or cloud-native VMs. This surely meets the demands of robust enterprise data security needs, but clients or applications that operate under extremely high performance, with ultra-low latency and high-throughput requirements, can further satisfy their SLAs/needs by performing certain cryptographic operations locally using Fortanix DSM Accelerator.

For more information about the Fortanix DSM Accelerator, refer to DSM Accelerator-Concepts.

This article describes the Fortanix DSM Accelerator PKCS#11 configurations and supported features.

2.0 Downloads

The latest version of Fortanix DSM Accelerator PKCS#11 can be downloaded here.

For information on Fortanix DSM Accelerator PKCS#11 deployment and installation, refer to DSM Accelerator PKCS#11 Deployment.

3.0 Configuration File

By default, the PKCS#11 client configuration file is located at /etc/fortanix/pkcs11.conf.

Refer to the following sample configuration file:

api_key = "FEL/ME...j+bt7"
api_endpoint = "https://apps.smartkey.io" # default is "https://apps.smartkey.io"
cache_ttl=1800 # cache TTL
retry_timeout_millis=5000
availability=false
unwrapping_keys="/path/to/unwrapping/keys"

The following table lists the configuration file variables and the configuration properties:

VARIABLE	PROPERTIES	TYPE	DESCRIPTION	DEFAULT VALUE
`api_endpoint`	`api.endpoint`	String	Specifies the API endpoint for communication with the Fortanix DSM.	`Api-endpoint;`
`api_key`	`api.key`	String	Specifies the API key used for authentication and authorization in Fortanix DSM.	`Api-key`
`cache_ttl`	`cache_ttl`	Integer	Sets the Time to Live (TTL) for cached items in the Fortanix DSM Accelerator PKCS#11.	`3600` seconds
`retry_timeout_millis`	`na`	Integer	Sets the retry interval for key retrieval attempts in the Fortanix DSM Accelerator PKCS#11.	`30000` milliseconds.
`availability`	`na`	Boolean	Indicates whether to retain expired keys during network outages.	`false`
`unwrapping_keys`	`na`	String	Path to file or directory with unwrapping key list in JSON format.

3.1 Configure PKCS#11 Properties

3.1.1 Time-Based Expiration Policy

Fortanix DSM Accelerator PKCS#11 supports a “time-based expiration policy” - TTL for its cache. This feature allows you to set the expiration time for all the keys being cached by Fortanix DSM Accelerator.

cache_ttl=1800 # cache TTL

You can configure this value as per your application requirements and/or use case by providing the cache_ttl environment variable with a value in seconds (unit of time). For example, cache_ttl=1800.
By default, this value is 3600 seconds (1 hour). This default value will apply in case the environment variable is not configured or set properly.

A cached entry will expire after the specified duration past from insert.
For example: cache_ttl=1200 seconds (20 mins).

ENTRY	INSERTED AT	EXPIRED AT
Key-1	12:00	12:10
key-2	12:10	12:20

The effective maximum cache_ttl for Fortanix DSM Accelerator PKCS#11 instance may be limited by an Administrative Policy set in Fortanix DSM in the future.

3.1.2 Retry Timeout

To configure the 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 = 60000 sets the retry limit to 60 seconds. The default value is 30000, which is 30 seconds.

3.1.3 Key Export Guardrails

The Key Export Guardrails feature enables Fortanix DSM Accelerator PKCS#11 Provider to enforce export permissions configured on security objects in Fortanix DSM.

When export restrictions are applied:

The client application can access the security object only in wrapped form.
Raw key material is never exposed.
Client access is limited to cryptographic operations only.

For more information on export permissions, refer to Export Policy.

Prerequisites:

Export permissions must be configured on the security object in Fortanix DSM.
Wrapping keys must be defined in the Export Permissions.

Perform the following steps to enable Key Export Guardrails on Fortanix DSM Accelerator PKCS#11:

Add the wrapping keys configured in the export policy in Fortanix DSM by specifying the file or directory paths where the list of unwrapping keys is in JSON format. These paths must be configured in the PKCS#11 configuration file along with dir or file format specifiers, where dir represents the directory of files and file represents the individual file path.
- Directory-based configuration:
```
UNWRAPPING_KEYS="dir <directory-1-path> <directory-2-path> ..."
```
- File-based configuration:
```
unwrapping_keys="file <file-1-path> <file-2-path> ...""
```
NOTE

Specifying unwrapping_keys is mandatory when Key Export Guardrails are enabled.

Each file should contain a list of JSON objects describing the unwrapping keys.
```
[
    {
        "key": {
            "kid": "ce12f4fa-e518-4767-9c8e-c8e31feb82b8"
        },
        "unwrapping_key": "6qUAwWnaGuDMBBCyVi28MU/7HIk8ASYEKiTsJKlx+XM8="
    },
    {"key": {
            "kid": "ce12f4fa-e518-4767-9c8e-c8e31feb82b7"
        },
        "unwrapping_key": "6qUAwWnaGuDMBBCyVi28MU/7HIk8ASYEKiTsJKlx+XM8="
    },
    {"key": {
            "name": "pub-key"
        },
        "is_asymmetric": true,
        "unwrapping_key": "MIIG4gIBABDFSAKCAYEArgATnIEtv6Kf6+lBwJ+lWPv4XqV4yNR3MAr8VHjhbsBi1E6Pbh9cbU35sfUPb6JkaCLFuiejGqQxWUfhXhGIOz0k3R7ss4tY9TaZPI6zTVn6KbtD2ky8IqeQqPrMBFb6xtSMWk9UZtgjM+breqtMO1s77IfUvyk9DFT....."
    }
]
```
- The key field must be the security object descriptor (as configured in the Fortanix DSM Export permissions). Fortanix DSM supports wrapping by key ID (kid) or key name (name)in the export policy.
  - For enhanced security, only the following keys are supported:
    - AES (256-bit GCM) can wrap both symmetric and asymmetric keys.
    - RSA with OAEP SHA256 encryption padding can wrap symmetric keys only.
- The is_asymmetric field is optional. It indicates whether the wrapping key is asymmetric. The default value is false.
- The unwrapping_key field contains the key material used to unwrap the exported key in Base64-encoded format. For asymmetric wrapping, this should be the private key.

4.0 Supported Features

OPERATIONS	ALGORITHM	KEY SIZE, CURVE, OR MODE
Create	Supported algorithms for importing a key: AES, DES, DES3 as HEX	Supported key sizes or curves: AES - 128, 192, or 256 bits DES - 56 bits DES3 - 112 or 168 bits
Encrypt or Decrypt	Supported algorithms: AES, DES, DES3, RSA	Supported modes: AES- CBC, CBC (no padding), CFB, GCM, GCM (no padding), OFB DES,DES3- 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	Supported algorithms: RSA	Supported modes: RSA- CKM_RSA_PKCS, CKM_SHA224_RSA_PKCS, CKM_SHA1_RSA_PKCS, CKM_SHA256_RSA_PKCS, CKM_SHA384_RSA_PKCS, CKM_SHA512_RSA_PKCS, CKM_SHA224_RSA_PKCS_PSS, CKM_SHA256_RSA_PKCS_PSS, CKM_SHA384_RSA_PKCS_PSS, CKM_SHA512_RSA_PKCS_PSS

OPERATIONS

ALGORITHM

KEY SIZE, CURVE, OR MODE

Create

Supported algorithms for importing a key:

AES, DES, DES3 as HEX

Supported key sizes or curves:

AES - 128, 192, or 256 bits
DES - 56 bits
DES3 - 112 or 168 bits

Encrypt or Decrypt

Supported algorithms:

AES, DES, DES3, RSA

Supported modes:

AES- CBC, CBC (no padding), CFB, GCM, GCM (no padding), OFB
DES,DES3- 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