DSM-Accelerator Java SDK

Introduction

Welcome to the Fortanix Data Security Manager (DSM) Administration guide. The purpose of this article is to describe the DSM-Accelerator Java SDK Deployment process and its usage.

Overview

Fortanix DSM-Accelerator can be used to encrypt, decrypt, tokenize, or detokenize data as it enters or leaves an application at a very high throughput, so that there is negligible latency between the applications and the crypto interface. To know more about DSM-Accelerator, refer to the DSM-Accelerator-Concepts Guide.

Operating Systems Supported

The DSM-Accelerator Java DSK can be run on any operating system that supports Java. This has been tested on openJDK 8, openJDK 11, and openJDK 17.

Installation and Usage

Installation

Download the dsmAccelerator.so file from the Fortanix Downloads page.

Place it in /opt/fortanix directory.

Download DSM-Accelerator.jar from the support portal. Place the JAR in the classpath of the application or put it as a dependency in the project.

Supported Crypto Operations and Modes

  • Encrypt - Single Part
  • Decrypt - Single Part
  • Tokenization
  • Detokenization

Only the following symmetric encryption algorithms are supported today:

  • AES
  • DES
  • DES3

Cipher modes:

  • ECB
  • CBC
  • CBCNOPAD (CBC w/o padding)
  • CFB
  • CTR
  • GCM
  • CCM
  • OFB
  • KW (key wrap)
  • KWP (key wrap w padding)
  • FF1 (AES only) -- this is tokenization
  • FPE (AES only) – this is tokenization

Usage

  1. Instantiate the DSM-Accelerator client by passing the URL of Fortanix DSM.
    DSMAccelerator client = new DSMAccelerator("https://sdkms.test.fortanix.com");
  2. Clear the cache of the client if required.
    client.clearCache();
  3. Create an application in Fortanix DSM and copy the API Key.

    Pass the API Key to authenticate the client.

    client.auth(apiKey);
  4. Generate a key (security object) inside the application created above with “Export” permission.

    Supported types for the Key: AES, DES, DES3, Tokenization (for performing tokenization or detokenization operations).

    Enable “Export” permission on the key.

    Once the key is generated, copy the UUID.

    image-20220929-125312.pngFigure 1: Key UUID
  5.  Create a KID object using the UUID of the key.
    Kid kid = new Kid("c72fed8b-821b-41f3-ae49-5c97a1d2b75e");
  6. Perform encryption.
    String plainStr = "123456789000";
    EncryptResponse encryptResp = client.encrypt(EncryptRequest.builder()
    .setKid(kid)
    .setPlain(plainStr.getBytes())
    .setAlg(Algorithm.AES)
    .setMode(CipherMode.CBC)
    .build());
  7. Perform decryption.
    DecryptResponse decryptResp = client.decrypt(DecryptRequest.builder()
    .setKid(kid)
    .setCipher(encryptResp.getCipher())
    .setAlg(Algorithm.AES)
    .setMode(CipherMode.CBC)
    .setIv(encryptResp.getIv())
    .build());
    System.out.println("CBC mode | decrypted to " + new String(decryptResp.getPlain(), StandardCharsets.UTF_8));
  8. Perform tokenization.
    encryptResp = client.encrypt(EncryptRequest.builder()
    .setKid(kid)
    .setPlain(plainStr.getBytes())
    .setAlg(Algorithm.AES)
    .setMode(CipherMode.FPE)
    .build());
    System.out.println("FPE mode | tokenized to " + new String(encryptResp.getCipher(),StandardCharsets.UTF_8));
  9. Perform detokenization.
    decryptResp = client.decrypt(DecryptRequest.builder() 
    .setKid(kid)
    .setCipher(encryptResp.getCipher())
    .setAlg(Algorithm.AES)
    .setMode(CipherMode.FPE)
    .setIv(encryptResp.getIv())
    .build());
  10. Close the session.
    client.terminate();

Comments

Please sign in to leave a comment.

Was this article helpful?
0 out of 0 found this helpful