DSM Accelerator JCE Provider Developer Guide

1.0 Introduction

Fortanix-Data-Security-Manager (DSM), in conjunction with Fortanix DSM Accelerator, provides a comprehensive application encryption and tokenization service. 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. You can cluster Fortanix DSM in geographically dispersed locations and deploy it 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 or needs by performing certain cryptographic operations locally using the Fortanix DSM Accelerator.

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

This article describes the Fortanix DSM Accelerator JCE Provider configurations and supported features.

2.0 Downloads

The latest version of the Fortanix DSM Accelerator JCE Provider can be downloaded here.

For information on Fortanix DSM Accelerator JCE Provider deployment and installation, refer to DSM Accelerator JCE Provider Deployment.

3.0 Examples

The Foratnix DSM Accelerator JCE example project is Maven-built and supports Java 17. It is intended to operate smoothly in any integrated development environment (IDE). This project includes example codes of performing cryptographic operations from Fortanix Data Security Manager (DSM).

You can access the Fortanix DSM Accelerator JCE examples from here.

4.0 Configuration File

All the Fortanix DSM Accelerator JCE configurations should be supplied through a user-defined configuration file instead of an environment variable from Fortanix DSM and Fortanix DSM Accelerator 4.18 releases.

Refer to the following sample configuration file:

FORTANIX_API_ENDPOINT=<Api-endpoint>
FORTANIX_API_KEY=<Api-key>
FORTANIX_LOG_API=true
FORTANIX_LOG_DEBUG=true
RETRY_FOR=5000  
CACHE_TTL=2 
RUST_LOG=debug
LOG_FILE=/path/dsma.log

The file path can be passed using the following command:

-Dprovider.config=/home/abc/jce.properties

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

4.1 Configure the Properties

4.1.1 Time-Based Expiration Policy

To manage the expiration of cached keys, Fortanix DSM Accelerator JCE offers a Time to Live (TTL) parameter. The cache.ttl parameter allows you to define the expiration time for keys stored in the Fortanix DSM Accelerator JCE provider's cache.

cache.ttl=<seconds>

You can configure this value as per your application requirements by providing the cache.ttl environment variable with a value in seconds (unit of time).

Example:

cache.ttl=600

In this example, the value is set to 600 seconds, indicating that keys in the cache will expire after 600 seconds.

• By default, this value is 3600 seconds (60 minutes). This default value will apply in cases where the environment variable is not configured or set properly.

• A cached entry will expire after the specified duration past the insert.
  For example: cache.ttl=1200 seconds (20 minutes)

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

• The effective maximum cache.ttl for a Fortanix DSM Accelerator JCE provider instance may be limited by an Administrative Policy set in DSM in the future.

4.1.2 Proxy

To enhance flexibility, Fortanix DSM Accelerator JCE supports proxy configuration through the FORTANIX_PROXY environment variable. You can set this variable to specify the proxy settings for Fortanix DSM Accelerator JCE.

FORTANIX_PROXY http://{{username}}:{{password}}@{{host}}:{{port}}

Where,

• {{username}} and {{password}}: Refers to the optional parameters for proxy authentication.

• {{host}}: Refers to the proxy address of the server.

• {{port}}: Refers to the port number for proxy communication.

Example:

FORTANIX_PROXY http://administrator:password@91.126.249.149:2946

4.1.3 Policy Awareness

The Fortanix DSM Accelerator JCE provider ensures adherence to application and security object policies enforced by Fortanix DSM. This support for policy awareness enhances security measures within the Fortanix DSM Accelerator environment.

4.1.4 Client Certificate Authentication

To implement the certificate-based authentication in Fortanix DSM Accelerator JCE, configure the following Java properties:

System.setProperty("javax.net.ssl.keyStoreType", "jks");
System.setProperty("javax.net.ssl.keyStore", "<pkcs12_file_path>");
System.setProperty("javax.net.ssl.keyStorePassword", "<keystore_password>");

During SSL authentication, particularly in peer authentication mode, where the server authenticates the client, it requires a key pair and a client certificate to verify the identity of the client. The key pair is stored in a file referred to as a keystore. To access this keystore, the JDK's SSL provider relies on specific system properties, namely javax.net.ssl.keyStore and javax.net.ssl.keyStorePassword. Additionally, the property javax.net.ssl.keyStoreType defines the type of keystore in use, such as a PKCS#12 keystore.

4.1.5 Enhanced Logging

To capture detailed logs, in addition to Java application logs, Fortanix DSM Accelerator JCE offers a RUST_LOG parameter. The RUST_LOG parameter allows you to define the desired verbosity level for enhanced logging, providing flexibility in tailoring the amount of detail captured in the logs, ranging from debug to trace levels, based on your specific debugging or monitoring needs during initialization.

To enable enhanced logging, set the environment variable to any one of the given values:

RUST_LOG=debug/warn/info/error/trace

If enhanced logging is enabled by setting the RUST_LOG environment variable, the log directory should mandatorily exist on the system.

The path where the detailed logs will be generated should be configured as follows:

• For the Linux operating system:

  LOG_FILE=/home/user/files/logs/dsma.log

• For the Windows operating system:

  LOG_FILE=C:\Users\Admin\DSMA\logs\dsma.log

However, if the log file location is not configured as an environment variable, then the temporary (/temp) directory for the applicable operating system will be considered as the default log location.

Example:

• For the Linux operating system:

  LOG_FILE=/tmp/jni_dsma.log

• For the Windows operating system:

  LOG_FILE=C:\Users\Administrator\AppData\Local\Temp\2\jni_dsma.log

4.1.6 Retry Interval

To manage the key retrieval attempts, Fortanix DSM Accelerator JCE offers a Retry Interval parameter. The RETRY_FOR parameter allows you to define the duration for which the Fortanix DSM Accelerator JCE provider will attempt to retrieve a key before considering it unavailable.

You can configure this value as per your application requirements by providing the RETRY_FOR environment variable with a value in milliseconds (unit of time).

RETRY_FOR=50000 //(~50sec)

In this example, the value is set to 50000 milliseconds, indicating that any HTTP requests from the application will be retried for up to 50 seconds before being considered unsuccessful by Fortanix DSM Accelerator JCE.

4.1.7 Temporary Directory

Fortanix uses the system's temp directory to temporarily copy libdsmaccelerator.so in Linux (or dsmaccelerator.dll in Windows. If you want to specify a directory for this process, you can do it by configuring an environment variable FORTANIX_TEMP_DIR set to any valid folder in the filesystem with appropriate(write/modify) permissions to the application consuming Fortanix DSM Accelerator JCE.

Example:

• For the Linux operating system:

  FORTANIX_TEMP_DIR=/home/user/DSMA/temp/

• For the Windows operating system:

  FORTANIX_TEMP_DIR=C:\Users\User\DSMA\temp\

4.1.8 Key Export Guardrails

This feature allows Fortanix DSM Accelerator JCE Provider to interact with the export policy configured on a security object in Fortanix DSM, ensuring that the client app can access the security object only in a wrapped form, thereby restricting the app's access to only cryptographic operations.

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

Perform the following steps to enable this feature on Fortanix DSM Accelerator JCE Provider:

1. Set the following environment variable:

   WRAPPED_EXPORTS_ENABLED=true

   Alternatively, you can pass it in the properties file: The value is optional; the default is false.

   wrapped_exports_enabled=true

2. 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. The paths should be provided as space-separated values along with dir or file format specifiers, where dir represents the directory of files and file represents the individual file path.

   NOTE

   You must specify a value for UNWRAPPING_KEYS if WRAPPED_EXPORTS_ENABLED is set to true.

   • Using environment variables:

     UNWRAPPING_KEYS="dir <directory-1-path> <directory-2-path> ..."

     Or

     UNWRAPPING_KEYS="file <file-1-path> <file-2-path> ...."

   • Using properties file:

     unwrapping_keys=dir <directory-1-path> <directory-2-path> ...

     Or

     unwrapping_keys=file <file-1-path> <file-2-path> ...

   Each file should contain a list of JSON objects, as shown in the following example:

   [
       {
           "key": {
               "kid": "ce12f4fa-e518-4767-9c8e-c8e31feb82b8"
           },
           "unwrapping_key": "6qUAwWnaGuDMBBCyVi28MU/7HIk8ASYEKiTsJlx+XM8="
       },
       {"key": {
               "kid": "ce12f4fa-e518-4767-9c8e-c8e31feb82b7"
           },
           "unwrapping_key": "6qUAwWnaGuDMBBCyVi28MU/7HIk8ASYEKiTsJlx+XM8="
       },
       {"key": {
               "name": "pub-key"
           },
           "is_asymmetric": true,
           "unwrapping_key": "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"
       }
   ]

   • The key field should be the security object descriptor (as configured in the Fortanix DSM export policy). 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 only wrap symmetric keys.

   • The is_asymmetric field is optional, and the default value is false.

   • The unwrapping_key field should contain the key material of the unwrapping key in BASE64 format. For asymmetric keys, this should be the private key.

5.0 Generate and Manage the Keys

This section explains the procedure for encrypting, decrypting, signing, and verifying keys, as well as using Format Preserving Encryption (FPE) for added data security.

5.1 Generate Exportable Keys

Add the KeyOperation.EXPORT to the allowedkeyOperation list:

List<KeyOperations> allowedKeyOperations = new ArrayList<>();
allowedKeyOperations.add(KeyOperations.EXPORT);
allowedKeyOperations.add(KeyOperations.ENCRYPT);
allowedKeyOperations.add(KeyOperations.DECRYPT);
SecurityObjectParameterSpec parameterSpec = new SecurityObjectParameterSpec(allowedKeyOperations,false);
keyGenerator.init(size);
keyGenerator.init(parameterSpec);
SecretKey key = keyGenerator.generateKey();

5.2 Key Encryption

The following is the sample code for key encryption:

private static byte[] encrypt(Provider provider, String mode, String padding, SecretKey key, String PLAIN) throws NoSuchPaddingException, NoSuchAlgorithmException, InvalidAlgorithmParameterException, InvalidKeyException, IllegalBlockSizeException, BadPaddingException, InvalidParameterSpecException {
    String algorithm = String.format("AES_%d/%s/%s", 256, mode, padding);
    Cipher cipher = Cipher.getInstance(algorithm, provider);
    AlgorithmParameters params;
    if(Objects.equals(mode, GCM)){
       iv = new byte[ProviderConstants.GCM_IV_LEN];
       int tagLen = 128;
       params = AlgorithmParameters.getInstance("GCM");
       GCMParameterSpec gcmSpec = new GCMParameterSpec(tagLen, iv);
       params.init(gcmSpec);
       cipher.init(Cipher.ENCRYPT_MODE, key, params);
       cipher.updateAAD(AAD.getBytes());
    } else
    if (Objects.equals(mode, CTR)) {
       cipher.init(Cipher.ENCRYPT_MODE, key, new IvParameterSpec(iv));
    } else{
       params = cipher.getParameters();
       cipher.init(Cipher.ENCRYPT_MODE, key, params);
    }
       System.out.println("Plain text: " + PLAIN);
       // Encrypted content
       return cipher.doFinal(PLAIN.getBytes());
   }

5.3 Key Decryption

The following is the sample code for key decryption:

private static byte[] decrypt(Provider provider, String mode, String padding, SecretKey key, byte[] cipherBytes) throws NoSuchPaddingException, NoSuchAlgorithmException, InvalidAlgorithmParameterException, InvalidKeyException, IllegalBlockSizeException, BadPaddingException, InvalidParameterSpecException {
        String algorithm = String.format("AES_%d/%s/%s", 256, mode, padding);
        Cipher cipher = Cipher.getInstance(algorithm, provider);
        AlgorithmParameters params;
        if(Objects.equals(mode, GCM)){
            iv = new byte[ProviderConstants.GCM_IV_LEN];
            int tagLen = 128;
            params = AlgorithmParameters.getInstance("GCM");
            GCMParameterSpec gcmSpec = new GCMParameterSpec(tagLen, iv);
            params.init(gcmSpec);
            cipher.init(Cipher.DECRYPT_MODE, key, params);
            cipher.updateAAD(AAD.getBytes());
        } else
            if (Objects.equals(mode, CTR)) {
            cipher.init(Cipher.DECRYPT_MODE, key, new IvParameterSpec(iv));
        } else{
            params = cipher.getParameters();
            cipher.init(Cipher.DECRYPT_MODE, key, params);
        }
        // decrypt the same content
        return cipher.doFinal(cipherBytes);
    }

5.4 Key Sign

The following is the sample code for signing keys:

public static byte[] sign(Provider provider, String algorithm, RSAPrivateKeyImpl rsaPrivateKey, String pssParameterDigest, MGF1ParameterSpec mgf1ParameterSpec) throws UnsupportedEncodingException, InvalidKeyException, SignatureException, NoSuchAlgorithmException, InvalidAlgorithmParameterException {
byte[] data = "test".getBytes("UTF8");
        Signature sig = Signature.getInstance(algorithm, provider);
        if (mgf1ParameterSpec != null || pssParameterDigest != null) {
            sig.setParameter(new PSSParameterSpec(pssParameterDigest, "MGF1", mgf1ParameterSpec, 32, 1));
        }
        sig.initSign(rsaPrivateKey);
        sig.update(data);
        return sig.sign();
    }

5.5 Key Verify

The following is the sample code for verifying the keys:

public static boolean verify(Provider provider, String algorithm, RSAPublicKeyImpl rsaPublicKey, byte[] signatureBytes, String pssParameterDigest, MGF1ParameterSpec mgf1ParameterSpec) throws UnsupportedEncodingException, InvalidKeyException, SignatureException, NoSuchAlgorithmException, InvalidAlgorithmParameterException {
        byte[] data = "test".getBytes("UTF8");
        Signature sig = Signature.getInstance(algorithm, provider);
        if (mgf1ParameterSpec != null || pssParameterDigest != null) {
            sig.setParameter(new PSSParameterSpec(pssParameterDigest, "MGF1", mgf1ParameterSpec, 32, 1));
        }
        sig.initVerify(rsaPublicKey);
        sig.update(ByteBuffer.wrap(data));
        return sig.verify(signatureBytes);
    }

5.6 Format Preserving Encryption (FPE) Tokenization

The following is the sample code for generating tokenization objects:

private static byte[] tokenization(Provider provider, String mode, String padding, SecretKey key, String PLAIN) throws NoSuchPaddingException, NoSuchAlgorithmException, InvalidAlgorithmParameterException, InvalidKeyException, IllegalBlockSizeException, BadPaddingException {
        String algorithm = String.format("AES_%d/%s/%s", 256, mode, padding);
        Cipher cipher = Cipher.getInstance(algorithm, provider);
        AlgorithmParameters params = cipher.getParameters();
        cipher.init(Cipher.ENCRYPT_MODE, key, params);
        System.out.println("Plain text: " + PLAIN);
        // Encrypted content
        return cipher.doFinal(PLAIN.getBytes());
    }

5.7 FPE Detokenization

The following is the sample code for FPE de-tokenization:

private static byte[] detokenization(Provider provider, String mode, String padding, SecretKey key, byte[] cipherBytes) throws NoSuchPaddingException, NoSuchAlgorithmException, InvalidAlgorithmParameterException, InvalidKeyException, IllegalBlockSizeException, BadPaddingException {
        String algorithm = String.format("AES_%d/%s/%s", 256, mode, padding);
        Cipher cipher = Cipher.getInstance(algorithm, provider);
        AlgorithmParameters params = cipher.getParameters();
        // decrypt the same content
        cipher.init(Cipher.DECRYPT_MODE, key, params);
        return cipher.doFinal(cipherBytes);
    }

5.8 Generate and Verify HMAC Keys

The following is the sample code that shows how to initialize and generate an HMAC key:

private void testHMac(String algorithm, int digestSize) throws NoSuchAlgorithmException,
InvalidKeyException {
Mac mac = Mac.getInstance(algorithm, provider);
 // initialize the key
KeyGenerator keygenerator = KeyGenerator.getInstance(
com.fortanix.sdkms.jce.provider.constants.AlgorithmParameters.HmacSHA1, provider);
secretKey = keygenerator.generateKey();
mac.init(secretKey);
mac.update(data.getBytes());
 // get hmac
byte[] hmac = mac.doFinal();
assertNotEquals(hmac, null);
assertEquals(hmac.length, digestSize);
}

The following is the sample code for verifying the HMAC key values produced by the HMAC-SHA1 algorithm:

public void testHmacEquality() throws NoSuchAlgorithmException, InvalidKeyException {
Mac mac = Mac.getInstance(
      com.fortanix.sdkms.jce.provider.constants.AlgorithmParameters.HmacSHA1,
      provider);
// use the same secret key as used in Mac operation.
mac.init(secretKey);
mac.update(data.getBytes());
String hmac1 = Hex.encodeHexString(mac.doFinal(), false);
mac.update(data.getBytes());
String hmac2 = Hex.encodeHexString(mac.doFinal(), false);
// for same key and same data HMAC should be same
assertEquals(hmac1, hmac2);
// digest length should be 40 in hex
assertEquals(hmac1.length(), 40);
}

5.9 Encryption and Decryption Using RSA Keys

The following is the sample code to perform encryption and decryption using an RSA key:

 public void encryptAndDecryptUsingRSA() throws NoSuchPaddingException, NoSuchAlgorithmException, InvalidAlgorithmParameterException, InvalidKeyException, IllegalBlockSizeException, BadPaddingException {
        SobjectDescriptor rsaSobjDesc = new SobjectDescriptor().name(RSA_KEY_NAME);
        KeyObject keyObj = SdkmsKeyService.getKeyObject(rsaSobjDesc);
        Key key = new RSAPublicKeyImpl(keyObj);
        String algorithm = "RSA/PKCS1_V15/PKCS5PADDING";
        Cipher cipher = Cipher.getInstance(algorithm, provider);
        AlgorithmParameters params = cipher.getParameters();
        // Encryption
        cipher.init(Cipher.ENCRYPT_MODE, key, params);
        String PLAIN = "Hello World";
        System.out.println("Plain text: " + PLAIN);
        byte[] cipherBytes = cipher.doFinal(PLAIN.getBytes());
        String encodedCipher = Base64.getEncoder().encodeToString(cipherBytes);
        System.out.println("Encrypted to " + encodedCipher);
        // Decryption
        cipher.init(Cipher.DECRYPT_MODE, key, params);
        byte[] plainBytes = cipher.doFinal(cipherBytes);
        System.out.println("Decrypted to " + new String(plainBytes));
    }

6.0 Supported Crypto Operations and Modes

• Encrypt - Single Part

• Decrypt - Single Part

CRYPTO	ALGORITHM	MODE/METHOD	KEY SIZE/CURVE	PADDING SUPPORT	USE
Symmetric	AES	CBC	128/192/256 bits		Data Encryption or Decryption, Tokenization
		CBCNOPAD
		CFB
		CTR
		GCM
		ECB
		OFB
		FPE/FF1
Symmetric	DES	CBCNOPAD	56 bits		Data Encryption or Decryption
		CBC
		ECB
Symmetric	DES3	CBC	112/168 bits		Data Encryption or Decryption
		CBCNOPAD
		ECB
Symmetric	SHA-1	SHA-1	HMAC Key Length: Between 112 and 8192 bits		Message Digest, Mac Generate and Mac Verify, Key Generation
	SHA-2	SHA-1
		SHA-224
		SHA-256
		SHA-384
		SHA-512
	RIPEMD	RIPEMD-160
Asymmetric	RSA	SHA1	1024/2048/3072/4096/5120/6144/7168/8192 bits	PSS, PKCS#1 v1.5	Digital Signature sign or verify
		SHA256
		SHA384
		SHA512
				PKCS#1 v1.5, OAEP	Data Encryption or Decryption

7.0 Policies and Permissions

The Fortanix DSM Accelerator JCE provider 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. This operation exports the security object either from the Fortanix DSM Accelerator local cache (if it exists) or from the Fortanix DSM. By default, the 'Export' operation is disabled for all key types. Do not enable the operation unless required. It is more secure to keep the value of the key inside Fortanix DSM only.

  NOTE

  To cache security objects locally, Fortanix DSM Accelerator requires enabling export permission

• 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 cannot 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 cannot be used to verify data.

  NOTE

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

• Encrypt: This operation allows the key to be used for encryption. During encryption, data is converted from plain text 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.

  NOTE

  Fortanix DSM Accelerator JCE supports encryption using either the UUID (kid) or the name of the security object. While performing the encryption using the security object name, ensure that the endpoint is https://{{localhost}}/crypto/v1/encrypt.

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

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 can encrypt and decrypt the key while a security object can only encrypt the key, you will only be able to encrypt the key.

• The effective policy will be updated after exporting a security object from Fortanix DSM to the Fortanix DSM Accelerator JCE Provider.