Manage keys and encrypt with Java - Futurex Documentation

Use the FXCL Java API to manage CryptoHub key stores and choose between local application encryption and CryptoHub-backed encryption.

What you’ll build

You will:

Create an AES-256 key store through Java.
Encrypt and decrypt locally with a retrievable key.
Encrypt and decrypt on CryptoHub with a non-retrievable key and DPM header.
Rotate and delete a test key store.

Before you begin

Complete Install and authenticate FXCL. Confirm that Java can load both /usr/share/java/fxcl-java.jar and the native library in /usr/lib.

The validated AES-CBC examples do not provide authenticated integrity by themselves. Add an approved integrity control for application data.

Create a key store

import com.futurex.fxcl.crypto.KeyAlgo;
import com.futurex.fxcl.crypto.KeyUsage;
import com.futurex.fxcl.kmes.store.KeyStore;
import com.futurex.fxcl.kmes.store.KeyStoreInfo;
import com.futurex.fxcl.kmes.store.KeyStoreManager;

KeyStoreManager manager = new KeyStoreManager(server);

KeyStoreInfo info = new KeyStoreInfo();
info.setName("customer-data-encryption");
info.setKeyAlgo(KeyAlgo.AES);
info.setKeyBits(256);
info.setKeyUsage(KeyUsage.DEK);
info.setRetrievable(true);
info.setRotationPeriod("90 Days");

KeyStore store = manager.createStore(info);

KeyUsage.DEK creates a data-encryption key store. setRetrievable(true) permits local encryption.

Encrypt and decrypt locally

import com.futurex.fxcl.crypto.BlockCipherMode;
import com.futurex.fxcl.crypto.Decrypt;
import com.futurex.fxcl.crypto.Encrypt;
import com.futurex.fxcl.crypto.Padding;
import com.futurex.fxcl.crypto.SymCipherParams;

import javax.crypto.Cipher;
import java.nio.charset.StandardCharsets;
import java.util.Arrays;

byte[] plaintext = "application data".getBytes(StandardCharsets.UTF_8);

SymCipherParams params = new SymCipherParams();
params.setMode(BlockCipherMode.CBC);
params.setPadding(Padding.PKCS7);

Cipher encrypt = Encrypt.newCipher(store.getKey(), params);
byte[] ciphertext = encrypt.doFinal(plaintext);

Cipher decrypt = Decrypt.newCipher(store.getKey(), params);
byte[] recovered = decrypt.doFinal(ciphertext);

if (!Arrays.equals(plaintext, recovered)) {
    throw new IllegalStateException("Decrypted data does not match");
}

The operation runs in the Java process. Protect the endpoint and application memory as part of the key boundary.

Encrypt and decrypt on CryptoHub

Create a separate non-retrievable store:

KeyStoreInfo remoteInfo = new KeyStoreInfo();
remoteInfo.setName("customer-remote-encryption");
remoteInfo.setKeyAlgo(KeyAlgo.AES);
remoteInfo.setKeyBits(256);
remoteInfo.setKeyUsage(KeyUsage.DEK);
remoteInfo.setRetrievable(false);
remoteInfo.setRotationPeriod("90 Days");

KeyStore remoteStore = manager.createStore(remoteInfo);

Configure the remote operation and include a DPM header:

import com.futurex.fxcl.kmes.crypto.RemoteDecrypt;
import com.futurex.fxcl.kmes.crypto.RemoteEncrypt;
import com.futurex.fxcl.kmes.crypto.RemoteEncryptParams;

SymCipherParams cipherParams = new SymCipherParams();
cipherParams.setMode(BlockCipherMode.CBC);
cipherParams.setPadding(Padding.PKCS5);

RemoteEncryptParams remoteParams = new RemoteEncryptParams(server);
remoteParams.setCipherParams(cipherParams);
remoteParams.setUseHeader(true);
remoteParams.setUseRandomIV(true);

Cipher remoteEncrypt = RemoteEncrypt.newCipher(
    remoteStore.getKeyInfo(),
    remoteParams
);
byte[] remoteCiphertext = remoteEncrypt.doFinal(plaintext);

Cipher remoteDecrypt = RemoteDecrypt.newHeaderCipher(server);
byte[] remoteRecovered = remoteDecrypt.doFinal(remoteCiphertext);

if (!Arrays.equals(plaintext, remoteRecovered)) {
    throw new IllegalStateException("Remote decrypt did not match");
}

The DPM header identifies the key and cryptographic parameters required for decryption. Store the full header and ciphertext together.

Rotate and delete the store

manager.rotateStore(store);
manager.deleteStore(store.getInfo().getName());

Close JNI-backed objects when the application no longer needs them:

store.close();
server.close();

Prefer try-with-resources for KeyServer, Credential, and KeyStore.

Build and run

javac -cp /usr/share/java/fxcl-java.jar App.java

java -Djava.library.path=/usr/lib \
  -cp .:/usr/share/java/fxcl-java.jar \
  App

Verify it works

Require these results:

The Java API authenticates the Host API session.
A retrievable store completes the local round trip.
A non-retrievable store completes the CryptoHub-backed round trip.
DPM-header decryption recovers the original data.
Rotation succeeds.
The test stores are deleted.

Do not log API keys, passwords, clear keys, plaintext, ciphertext, or DPM header contents.

Troubleshooting

Signal	Cause	Action
`UnsatisfiedLinkError`	Java cannot locate the FXCL native library.	Set `-Djava.library.path=/usr/lib` and confirm `libfxcl.so` is installed.
Java login returns `LN=0`	The API key authenticated, but the role context needs finalization.	Send a separate `[AORKLO;LN1;]` request on the same connection.
Local `getKey` fails	The store is not retrievable or has no active key.	Use a retrievable store for the local path.
Remote encryption fails before processing data	The store is retrievable, the key usage is wrong, or the identity cannot run `RKED`.	Use a non-retrievable `DEK` store and verify the Host API command and partition.

Version and scope

This procedure was validated with FXCL 1.9.5, CryptoHub 7.2.0.7, Ubuntu 22.04, OpenSSL 3, and OpenJDK 17.

​What you’ll build

​Before you begin

​Create a key store

​Encrypt and decrypt locally

​Encrypt and decrypt on CryptoHub

​Rotate and delete the store

​Build and run

​Verify it works

​Troubleshooting

​Version and scope

What you’ll build

Before you begin

Create a key store

Encrypt and decrypt locally

Encrypt and decrypt on CryptoHub

Rotate and delete the store

Build and run

Verify it works

Troubleshooting

Version and scope