Manage keys and encrypt with C++ - Futurex Documentation

Use a retrievable CryptoHub key store to obtain the active AES key and perform encryption inside the C++ application process.

What you’ll build

The example performs this lifecycle:

Create a retrievable AES-256 key store.
Retrieve the active key through KeyStore.
Encrypt and decrypt data locally with AES-CBC and PKCS #7 padding.
Rotate the active key.
Delete the test key store.

Before you begin

Complete Install and authenticate FXCL. The authenticated partition must permit key-store create, retrieve, rotate, and delete operations.

AES-CBC provides confidentiality but not authenticated integrity. Protect the ciphertext with a separate integrity control, or use an approved authenticated construction that your application and Futurex product version support.

Create a retrievable key store

#include <fxcl/KeyAlgo.h>
#include <fxcl/KeyUsage.h>
#include <fxcl/TimePeriod.h>
#include <fxcl/TimeUnit.h>
#include <fxcl/kmes/KeyStore.h>
#include <fxcl/kmes/KeyStoreInfo.h>
#include <fxcl/kmes/KeyStoreManager.h>

fxcl::kmes::KeyStoreManager manager(server);

fxcl::kmes::KeyStoreInfo info;
info.setName("customer-data-encryption");
info.setKeyAlgo(fxcl::KeyAlgo::AES);
info.setKeyBits(256);
info.setKeyUsage(
    fxcl::KeyUsage::Encrypt | fxcl::KeyUsage::Decrypt
);
info.setRetrievable(true);
info.setRotationPeriod(
    fxcl::TimePeriod(fxcl::TimeUnit::Day, 90)
);

fxcl::kmes::KeyStore store;
if (!manager.createStore(info, store) || !store.isValid()) {
    throw std::runtime_error(manager.getError().c_str());
}

setRetrievable(true) permits FXCL to return the active key for a client-side operation. The clear key can enter application memory. You should receive a valid KeyStore with an active SecretKey.

Encrypt and decrypt locally

#include <fxcl/BlockCipherMode.h>
#include <fxcl/ByteArray.h>
#include <fxcl/Decrypt.h>
#include <fxcl/Encrypt.h>
#include <fxcl/Padding.h>
#include <fxcl/SymCipherParams.h>

const fxcl::ByteArray plaintext("application data");
fxcl::ByteArray ciphertext;
fxcl::ByteArray recovered;

fxcl::SymCipherParams params;
params.setMode(fxcl::BlockCipherMode::CBC);
params.setPadding(fxcl::Padding::PKCS7);

fxcl::Encrypt encrypt;
encrypt.setKey(store.getKey());
encrypt.setParams(params);
if (!encrypt.encrypt(plaintext, ciphertext)) {
    throw std::runtime_error("FXCL encryption failed");
}

fxcl::Decrypt decrypt;
decrypt.setKey(store.getKey());
decrypt.setParams(params);
if (!decrypt.decrypt(ciphertext, recovered)) {
    throw std::runtime_error("FXCL decryption failed");
}

if (recovered != plaintext) {
    throw std::runtime_error("Decrypted data does not match");
}

Store the initialization vector and cipher parameters with the ciphertext. Decryption must use the same parameters and the key version that encrypted the data. You should recover the original byte sequence exactly.

Rotate the key store

if (!manager.rotateStore(store)) {
    throw std::runtime_error(manager.getError().c_str());
}

Rotation creates a new active key and expires the prior active key. Keep the key identifier or DPM header with existing ciphertext so the application can select the correct historical key for decryption.

Delete a test key store

if (!manager.deleteStore("customer-data-encryption")) {
    throw std::runtime_error(manager.getError().c_str());
}

Deleting a key store can make its ciphertext unrecoverable. Delete only test-owned stores or stores that completed the approved retention and destruction process.

Build the application

g++ -std=c++17 -O2 -Wall -Wextra \
  -DFXCL_OSSL_3 app.cpp \
  -o app \
  -lfxcl -pthread

The FXCL_OSSL_3 definition must match the installed OpenSSL 3 package.

Verify it works

Use a dedicated test store and a known plaintext. Require all of these results:

createStore returns a valid store.
getKey returns the active AES key.
The decrypt result exactly matches the input.
rotateStore succeeds.
deleteStore removes the test store.

Do not record the API key, active key, plaintext, ciphertext, or decrypted value in application logs.

Troubleshooting

Signal	Cause	Action
Key-store creation fails	The identity lacks the key-store operation or the Host API command is disabled.	Verify the partition, Excrypt port, and `RKCS`, `RKCK`, and `RKES` command availability.
Local encryption cannot get a key	The store is non-retrievable or has no active key.	Use a retrievable store for client-side encryption and confirm an active key exists.
Decryption returns different data	The key version, IV, mode, or padding does not match encryption.	Persist and restore the full encryption context.
Old ciphertext fails after rotation	The application selected only the new active key.	Retain the original key identifier or use a DPM header to select the historical key.

Version and scope

This procedure was validated with FXCL 1.9.5, CryptoHub 7.2.0.7, Ubuntu 22.04, GCC 11, and the OpenSSL 3 FXCL package.

​What you’ll build

​Before you begin

​Create a retrievable key store

​Encrypt and decrypt locally

​Rotate the key store

​Delete a test key store

​Build the application

​Verify it works

​Troubleshooting

​Version and scope

What you’ll build

Before you begin

Create a retrievable key store

Encrypt and decrypt locally

Rotate the key store

Delete a test key store

Build the application

Verify it works

Troubleshooting

Version and scope