> ## Documentation Index
> Fetch the complete documentation index at: https://docs.futurex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Install and authenticate FXCL

> Install FXCL 1.9.5 for C++ and Java, configure strict TLS to the CryptoHub Native Host API, and authenticate an application session.

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:

```text theme={null}
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

<Steps>
  <Step title="Select the OpenSSL 3 packages">
    Obtain the FXCL 1.9.5 AMD64 OpenSSL 3 packages from the Futurex software distribution channel:

    ```text theme={null}
    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`.
  </Step>

  <Step title="Install the packages">
    ```bash theme={null}
    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.
  </Step>

  <Step title="Confirm the installed files">
    ```bash theme={null}
    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`.
  </Step>
</Steps>

## Configure TLS in C++

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

```cpp theme={null}
#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:

```cpp theme={null}
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:

```java theme={null}
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:

```bash theme={null}
# 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.


## Related topics

- [Install and configure the FXCL CNG](/Integrations/KMES_Series_3/Certificate_Authority/Microsoft_ADCS/Install_and_configure_the_FXCL_CNG.md)
- [Install and configure FXCL CNG](/Integrations/CryptoHub/Credential_management/Microsoft_OCSP/Install_and_configure_FXCL_CNG.md)
- [Install and configure FXCL EKM](/Integrations/CryptoHub/Database/Microsoft_SQL_Server/Install_and_configure_FXCL_EKM.md)
- [Install FXCLI](/Integrations/HSM/DNS/BIND/Integration_steps/Install_FXCLI.md)
- [Install and configure Futurex FXCL CNG](/Integrations/CryptoHub/Generic/Generic_Futurex_CNG/Install_and_configure_Futurex_FXCL_CNG.md)