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:

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:

1. 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

5.0 Supported Algorithms and Modes

CRYPTO	ALGORITHM	MODE/METHOD	KEY SIZE/CURVE	USE
Symmetric	AES	CBC	128/192/256 bits	Data Encryption or Decryption, Tokenization
		CBCNOPAD
		CFB
		OFB
		GCM
Symmetric	DES	CBCNOPAD	56 bits	Data Encryption or Decryption
		CBC
Symmetric	DES3	CBC	168 bits	Data Encryption or Decryption
		CBCNOPAD
Symmetric	SHA-1	SHA-1	HMAC Key Length: Between 112 and 8192 bits	Mac Generate and Mac Verify, Key Generation
	SHA-2	SHA-1
		SHA-224
		SHA-256
		SHA-384
		SHA-512
	RIPEMD	RIPEMD-160
Asymmetric	RSA	CKM_RSA_PKCS	1024, 2048, 3172, 4096, 5120, 6144, 7168, 8192 bits Exponent = [65537, 3]	Digital Signature sign or verify
		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

6.0 Policies and Permissions

Fortanix DSM Accelerator PKCS#11 honors the following policies for both security objects and apps as defined in the Fortanix DSM user interface.

• Export - This operation enables the security object to be retrieved with an authenticated request. By default, the 'Export' operation is disabled for all key types. The operation should not be enabled unless required. It is more secure to keep the value of the key inside Fortanix DSM only.

  NOTE

  Fortanix DSM Accelerator requires the export permission to be enabled for the security objects to be cached locally.

• Sign - This operation enables the key to be used for generating a digital signature. The signing key must be an asymmetric key such as RSA, DSA, or elliptical key, with the private part present. The symmetric keys may not be used to sign data.

• Verify - This operation enables the key to be used for verifying a signature. The verifying key must be an asymmetric key such as RSA, DSA, or elliptical curve key, with the ‘Verify’ operation enabled. The symmetric keys may not be used to verify data.

  NOTE

  Currently, Fortanix DSM Accelerator only supports RSA and EC asymmetric keys for Sign and Verify.

• Encrypt - This operation allows the key to be used for encryption. Encryption involves the process of converting data from plain text format to an encoded format called ciphertext using a key generated by an algorithm. Both asymmetric and symmetric keys can be used to perform the ‘Encrypt’ operation.

• Decrypt - This operation allows the key to be used for decryption. Decryption involves the process of converting ciphertext into plaintext using a key. Both asymmetric and symmetric keys can be used to perform the ‘Decrypt’ operation.

• Assistance with awareness of security object policies: Fortanix DSM Accelerator PKCS#11 enforces security object policy from the upstream Fortanix DSM.

NOTE

• The effective policy is the largest set of permissions contained in both the set of app and security object permissions. For example, if an app is permitted to perform encryption and decryption operations using the key, and the security object is only permitted to perform encryption, then you will only be able to perform encryption using the key.

• The effective policy will be updated after exporting a security object from Fortanix DSM to Fortanix DSM Accelerator PKCS#11.