DSM Accelerator JCE Provider Deployment

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.

This article describes the Fortanix DSM Accelerator JCE Provider deployment steps.

2.0 Supported Operating Systems

The supported operating systems (OS) for the Fortanix DSM Accelerator Unified JCE SDK client have been tested on OpenJDK 8, OpenJDK 11, and OpenJDK 17.

For information on the Fortanix DSM Accelerator Unified JCE SDK client OS compatibility matrix, refer to DSM Accelerator - Compatibility Matrix.

3.0 Java Archive (JAR) Files

Thin and Fat jars are terminologies commonly used in Java development, particularly in the context of Java Archive (JAR) files.

Thin JAR: A thin JAR typically contains only the class files and resources necessary for running an application. It does not include any third-party dependencies. When you build a thin JAR, you must ensure that all the required dependencies are available in the runtime environment where the JAR will be executed. Thin JARs are often smaller in size compared to fat JARs because they don't include external dependencies. The typical JAR package contains three thin JARs bundled in a zip file.
Unified Thin JAR: It is similar to a thin JAR, but it comes with all the Fortanix dependencies bundled within a single JAR. You still need to ensure that all the required third-party dependencies are available in the runtime environment where the JAR will be executed. This serves as an alternative to the thin JAR, eliminating the need to manually install and maintain Fortanix dependencies separately.
Fat (Bundled) JAR: A fat JAR, on the other hand, contains not only the application's classes and resources but also all of its dependencies. This means that the JAR file includes all the necessary libraries and dependencies bundled within it. You can easily distribute and run fat JARs on any system with the Java Runtime Environment (JRE) installed without worrying about external dependencies, making them convenient. However, they tend to be larger compared to thin JARs because they include all dependencies.

The choice between using thin and fat JARs depends on factors like deployment environment, distribution preferences, and the size constraints of the application.

4.0 Deploy Fortanix DSM Accelerator JCE Provider

Fortanix DSM Accelerator supports the following methods to deploy JCE Provider JAR files:

Using bundled JARs.
Using thin JARs uploaded to the user's private Maven repository.
Using thin JARs by adding them as an external library in the Maven project.

NOTE
Before deploying, ensure that your system meets the prerequisites for deploying the Fortanix DSM Accelerator JCE Provider. This may include hardware requirements, supported operating systems, and any dependencies needed for the installation.

4.1 Using Bundled JARs

In this method, you must add the bundled jars as an external library.

You can download the bundled jars with all external dependencies from DSM Accelerator JCE Provider.

4.2 Using Thin JARs Uploaded to Private Maven Repository

Perform the following steps:

Download the Fortanix DSM Accelerator JCE thin JARs package from DSM Accelerator JCE Provider.
The downloaded zip file contains three thin JARs.
Example:
- sdkms-jce-provider-dsma-4.26.2375.jar
- sdkms-client-4.26.2375.jar
- dsm-accelerator-4.26.2375.jar
Open each JAR file from the file explorer and find the corresponding pom.xml located at META-INF/maven/com.fortanix/<artifactId>/pom.xml.

Run the following comand to install all the thin JARs:

mvn install:install-file -Dfile=<jarfile> -DpomFile=<extracted_pom>

After a successful installation, add the following dependencies to your pom.xml.

The following is an example of the Fortanix DSM Accelerator JCE version 4.28.2410:

<dependency>
    <groupId>com.fortanix</groupId>
    <artifactId>sdkms-jce-provider-dsma</artifactId>
    <version> 4.28.2410</version>
</dependency>
<dependency>
    <groupId>com.fortanix</groupId>
    <artifactId>sdkms-client</artifactId>
    <version> 4.28.2410</version>
</dependency>
<dependency>
    <groupId>com.fortanix</groupId>
    <artifactId>dsm-accelerator</artifactId>
    <version> 4.28.2410</version>
</dependency>

4.2.1 Adding Unified Thin JAR Uploaded to Private Maven Repository

Perform the following steps:

Download the Fortanix DSM Accelerator JCE unified thin JAR from DSM Accelerator JCE Provider.
The downloaded file is a JAR file. For example, sdkms-jce-provider-minimal-dsma-4.31.2447.jar.
Open the JAR file from the file explorer and locate the pom.xml.

Run the following command to install the JAR:

mvn install:install-file -Dfile=<jarfile> -DpomFile=<extracted_pom>

After a successful installation, add the following dependencies to your pom.xml.

The following is an example of the Fortanix DSM Accelerator JCE version 4.31.2447:

<dependency>
    <groupId>com.fortanix</groupId>
    <artifactId>sdkms-jce-provider-minimal-dsma</artifactId>
    <version> 4.31.2447</version>
</dependency>

4.3 Using a Thin JAR as an External Library in the Maven

Perform the following steps:

Download the Fortanix DSM Accelerator JCE thin jar package from DSM Accelerator JCE Provider.
The downloaded zip file contains three thin JARs.
Example:
- sdkms-jce-provider-dsma-4.26.2375.jar
- sdkms-client-4.26.2375.jar
- dsm-accelerator-4.26.2375.jar
Open each JAR file from the file explorer and find the corresponding pom.xml located at META-INF/maven/com.fortanix/<artifactId>/pom.xml

Open each pom.xml file and identify the respective dependencies. Then, add those dependencies to your Maven project.

Refer to the following dependencies used by the thin JARs in your Maven project:

<dependencies>
 <dependency>
   <groupId>org.apache.logging.log4j</groupId>
   <artifactId>log4j-slf4j-impl</artifactId>
   <version>2.22.1</version>
 </dependency>
 <dependency>
   <groupId>co.nstant.in</groupId>
   <artifactId>cbor</artifactId>
   <version>0.9</version>
 </dependency> 
<!-- HTTP client: jersey-client -->
<dependency>
  <groupId>org.glassfish.jersey.core</groupId>
  <artifactId>jersey-client</artifactId>
  <version>3.0.11</version>
</dependency>
<dependency>
  <groupId>org.apache.commons</groupId>
  <artifactId>commons-lang3</artifactId>
  <version>3.12.0</version>
</dependency>
<dependency>
  <groupId>org.glassfish.jersey.media</groupId>
  <artifactId>jersey-media-multipart</artifactId>
  <version>3.0.11</version>
</dependency>
<dependency>
  <groupId>org.glassfish.jersey.media</groupId>
  <artifactId>jersey-media-json-jackson</artifactId>
  <version>3.0.11</version>
</dependency>
<dependency>
  <groupId>org.glassfish.jersey.connectors</groupId>
  <artifactId>jersey-apache-connector</artifactId>
  <version>3.0.11</version>
</dependency>
<dependency>
  <groupId>org.glassfish.jersey.inject</groupId>
  <artifactId>jersey-hk2</artifactId>
  <version>3.0.11</version>
</dependency>
<!-- JSON processing: jackson -->
<dependency>
  <groupId>com.fasterxml.jackson.core</groupId>
  <artifactId>jackson-core</artifactId>
  <version>2.14.2</version>
</dependency>
<dependency>
  <groupId>com.fasterxml.jackson.core</groupId>
  <artifactId>jackson-annotations</artifactId>
  <version>2.14.2</version>
</dependency>
<dependency>
  <groupId>com.fasterxml.jackson.core</groupId>
  <artifactId>jackson-databind</artifactId>
  <version>2.14.2</version>
</dependency>
<dependency>
  <groupId>com.github.joschi.jackson</groupId>
  <artifactId>jackson-datatype-threetenbp</artifactId>
  <version>2.6.4</version>
</dependency>
<!-- Base64 encoding that works in both JVM and Android -->
<dependency>
  <groupId>com.brsanthu</groupId>
  <artifactId>migbase64</artifactId>
  <version>2.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/jakarta.ws.rs/jakarta.ws.rs-api -->
<dependency>
  <groupId>jakarta.ws.rs</groupId>
  <artifactId>jakarta.ws.rs-api</artifactId>
  <version>3.0.0</version>
</dependency>
</dependencies>

4.3.1 Adding Unified Thin JAR as an External Library in the Maven

Perform the following steps:

Download the Fortanix DSM Accelerator JCE unified thin JAR from DSM Accelerator JCE Provider.
The downloaded file is a JAR file. For example, sdkms-jce-provider-minimal-dsma-4.31.2447.jar.
Open the JAR file from the file explorer and locate the pom.xml.
Open the pom.xml file and identify the respective dependencies. Then, add those dependencies to your Maven project. For more information on the dependencies, refer to Step 5 in Section 4.3: Using a Thin JAR as an External Library in the Maven.

5.0 Install the Dependencies

Perform the following steps to install the required libraries:

Download the unified JCE and Java SDK JAR for Java 8, Java 11, or Java 17 from DSM Accelerator JCE Provider.
Run the following command to set the CA certificate using the ca_file environment for the JCE jar:
```
ca_file=/home/user/cacarts/cacerts1
```
The CA certificate-supported formats are PEM and DER.

5.1 Set Up Fortanix DSM Accelerator with Certificate

To authenticate the Fortanix DSM Accelerator using a certificate, it is necessary to create an x509 certificate and add it to OpenSSL PKCS12 keystore.

Perform the following steps:

Create a Fortanix DSM application (app) and note the UUID for using it in later steps.
Run the following OpenSSL command to generate a x509 client certificate along with its private key:
```
$ openssl req -x509 -sha256 -nodes -days 3650 -newkey rsa:4096 -keyout client_pkey.key -out client_cert.pem
```
NOTE
Alternatively, you can create the client certificate by passing in an App ID. For more information, refer to Authentication.
Run the following command to generate an OpenSSL PKCS#12 keystore and add the client certificate along with its private key to the generated keystore:
```
$ openssl pkcs12 -export -out myp12.p12 -inkey client_pkey.key -keypbe AES-256-CBC -in client_cert.pem -certpbe AES-256-CBC
```
NOTE
- When executing this command, you will be prompted to enter a password, and this password will serve as the key to access the keystore. Ensure to remember this value for using it for javax.net.ssl.keyStorePassword property.
- In OpenSSL version 1.1.1f, it is essential to specify a non-legacy encryption algorithm, such as AES-256-CBC, for the -keypbe and -certpbe attributes. For more information on identifying algorithms marked as 'legacy' in updates to OpenSSL version 3.0 and above, refer to the OpenSSL official documentation.

Modify the authentication method type to Certificate for the required app and upload the client certificate generated in Step 2. For more information, refer to Authentication.

 Example Java Program (compatible with openJDK Java 8, 11, and 17):
    package com.fortanix.auth.cert;
    import com.fortanix.sdkms.jce.provider.SdkmsJCE;
    public class Main {
    public static void main(String[] args) {
    System.setProperty("javax.net.ssl.keyStoreType", "jks");
    System.setProperty("javax.net.ssl.keyStore", "<pkcs12_file_path>");
    System.setProperty("javax.net.ssl.keyStorePassword", "<keystore_password>");
    /* Setting up SdkmsJCE for certificate-based authentication is different
    from the usual process with API-key authentication. Instead of using the
    apiKey when initializing SdkmsJCE, for certificate-based authentication,
    you need to provide the app's UUID (app_ID). */
    SdkmsJCE sdkmsJCE = SdkmsJCE.initialize("https://apps.smartkey.io",
    "<app_id>");
    }
    }

6.0 Additional References

For information on Fortanix DSM Accelerator JCE Provider configurations and supported features, refer to the DSM Accelerator JCE Provider Developer Guide.
For more information about the Fortanix DSM Accelerator, refer to DSM Accelerator-Concepts.