Install and authenticate FXCL - Futurex Documentation

This guide installs the FXCL C++ and Java APIs and establishes an authenticated TLS connection to CryptoHub.

What you’ll build

You will configure an application host with:

The FXCL native library and C++ headers
The FXCL Java archive and JNI path
Strict TLS trust for the CryptoHub production endpoint
A Client Application API-key login for key and profile operations

Before you begin

You need:

CryptoHub 7.2.0.x with port 2001 reachable. FXCL uses the Native Host API, not the CryptoHub v2 REST transport.
The CryptoHub production CA and expected TLS server name. The client must verify CryptoHub before it sends credentials or application data.
A Client Application identity assigned to a non-management partition. Enable the Excrypt port and grant only the key-store, crypto, and token-profile operations the application uses.
The FXCL package for the host architecture and OpenSSL family. The native package is ABI-specific. Do not install an OpenSSL 1.1 package on an OpenSSL 3 host.

For the workflows in this guide, enable these Host API commands as applicable:

RKLO RKLN RKCS RKCK RKES RKVS RKDS RKRG RKED
TKGA TKGG TKGD TOKA TOKG

RKLO authenticates the application. The RK* commands manage and use key stores. TKG* manages tokenization profiles. TOKA and TOKG perform remote tokenization and detokenization.

Install the Linux packages

Select the OpenSSL 3 packages

Obtain the FXCL 1.9.5 AMD64 OpenSSL 3 packages from the Futurex software distribution channel:

fxcl-1.9.5-linux-amd64-ssl3-devel.deb
fxcl-1.9.5-linux-amd64-ssl3-java.deb

The development package installs libfxcl.so, the C++ headers, and C++ examples. The Java package installs fxcl-java.jar.

Install the packages

sudo dpkg -i \
  ./fxcl-1.9.5-linux-amd64-ssl3-devel.deb \
  ./fxcl-1.9.5-linux-amd64-ssl3-java.deb

You should see both packages finish with Setting up and no dependency error.

Confirm the installed files

test -f /usr/lib/libfxcl.so
test -f /usr/share/java/fxcl-java.jar
test -d /usr/include/fxcl

Each command must exit with status 0.

Configure TLS in C++

Load the production CA, set the expected server name, and connect to port 2001:

#include <cstdlib>
#include <set>

#include <fxcl/Init.h>
#include <fxcl/kmes/KeyServer.h>
#include <fxcl/tls/Config.h>
#include <fxcl/tls/Credential.h>

fxcl::Init::init();

fxcl::tls::Config tls;
tls.setEnabled(true);
tls.setAnonymous(true); // Server-authenticated TLS; no client certificate.
tls.setServerName("cryptohub.example.com");
tls.setProtocols({
    fxcl::tls::Protocol::TLSv1_2,
    fxcl::tls::Protocol::TLSv1_3
});

fxcl::tls::Credential credential;
if (!credential.loadCA("/etc/futurex/cryptohub-production-ca.pem") ||
    !credential.validateTrustedPki()) {
    throw std::runtime_error("CryptoHub CA validation failed");
}

fxcl::kmes::KeyServer server;
server.setTlsConfig(tls);
server.setTlsCredential(credential);
server.setAddress("cryptohub.example.com", 2001);
if (!server.connect()) {
    throw std::runtime_error(server.getError().c_str());
}

setAnonymous(true) means the TLS connection does not send a client certificate. It does not disable server verification when a trusted CA and server name are configured.

Authenticate in C++

Keep the API key outside source code and command arguments. Load it from a protected environment or secret provider:

const char *apiKey = std::getenv("FXCL_API_KEY");
if (apiKey == nullptr || *apiKey == '\0') {
    throw std::runtime_error("FXCL_API_KEY is not available");
}

server.getMessageSender().setAuthToken(apiKey, true);

The second argument identifies the token as a Client Application API key rather than a JWT.

Configure and authenticate Java

The Java binding uses KeyServer, Config, and Credential. Connect with the DNS name in the CryptoHub production certificate:

import com.futurex.fxcl.JniInit;
import com.futurex.fxcl.excrypt.ExcryptMessage;
import com.futurex.fxcl.kmes.server.KeyServer;
import com.futurex.fxcl.tls.Config;
import com.futurex.fxcl.tls.Credential;
import com.futurex.fxcl.tls.Protocol;

import java.util.EnumSet;

JniInit.init();

Config tls = new Config();
tls.setEnabled(true);
tls.setAnonymous(true);
tls.setProtocols(EnumSet.of(Protocol.TLSv1_2, Protocol.TLSv1_3));

Credential credential = new Credential();
credential.loadCA("/etc/futurex/cryptohub-production-ca.pem");

KeyServer server = new KeyServer();
server.setTlsConfig(tls);
server.setTlsCredential(credential);
server.setAddress("cryptohub.example.com", 2001);
server.connect();

String apiKey = System.getenv("FXCL_API_KEY");
if (apiKey == null || apiKey.isBlank()) {
    throw new IllegalStateException("FXCL_API_KEY is not available");
}

ExcryptMessage login = server.sendMessage(
    new ExcryptMessage("[AORKLO;AP" + apiKey + ";]")
);
if (!"Y".equals(login.getTag("AN"))) {
    throw new IllegalStateException("FXCL API-key login failed");
}

if (login.getTagInt("LN", 0) == 0) {
    ExcryptMessage finalized = server.sendMessage(
        new ExcryptMessage("[AORKLO;LN1;]")
    );
    if (!"Y".equals(finalized.getTag("AN")) ||
        finalized.getTagInt("LN", 0) != 1) {
        throw new IllegalStateException("FXCL role login is incomplete");
    }
}

Some partitions require a separate LN1 request after API-key authentication. Do not replace or rotate a valid API key only because the first response reports LN=0.

Verify it works

Compile and run a connection check before you create keys:

# C++
g++ -std=c++17 -DFXCL_OSSL_3 app.cpp -o app -lfxcl -pthread

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

A successful check must establish TLS, return AN=Y from RKLO, and complete any required LN1 finalization with LN=1.

Troubleshooting

Signal	Cause	Action
`Missing OpenSSL version definition`	The C++ build did not select the FXCL OpenSSL ABI.	Add `-DFXCL_OSSL_3` for the OpenSSL 3 package.
TLS connection failure	The CA, server name, port, or selected FXCL OpenSSL package does not match the endpoint.	Verify the production CA, certificate identity, port 2001, and package family.
`USER NOT LOGGED IN`	The operation ran before `RKLO` completed.	Authenticate and send a separate `LN1` request when the first login returns `LN=0`.
`FUNCTION NOT SUPPORTED`	CryptoHub does not have the required Host API command enabled.	Enable only the commands required by the application workflow.

Version and scope

These steps were validated with FXCL 1.9.5, CryptoHub 7.2.0.7, Ubuntu 22.04, GCC 11, OpenSSL 3, and OpenJDK 17.

​What you’ll build

​Before you begin

​Install the Linux packages

​Configure TLS in C++

​Authenticate in C++

​Configure and authenticate Java

​Verify it works

​Troubleshooting

​Version and scope