> ## 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 configure Futurex PKCS #11

> Install the Futurex PKCS #11 library 6.5 for Oracle Solaris SPARC where Oracle Database finds HSM libraries, place the endpoint configuration, and test the connection to CryptoHub.

Install the Futurex PKCS #11 library on the Solaris server, and then place the endpoint configuration where the library finds it. Run the commands on this page as root, unless a step says otherwise.

## Extract the endpoint bundle

<Steps>
  <Step>
    Copy the endpoint ZIP file to the Solaris server, and then extract it to a staging directory:

    ```shell wrap theme={null}
    mkdir -p /var/tmp/fxpkcs11
    cd /var/tmp/fxpkcs11
    unzip /path/to/ENDPOINT_ZIP_FILE.zip
    ```
  </Step>

  <Step>
    Confirm that the library is the 64-bit SPARC build:

    ```shell wrap theme={null}
    file libfxpkcs11.so
    ```

    <Check>
      The output contains `ELF 64-bit MSB dynamic lib SPARCV9`.
    </Check>
  </Step>

  <Step>
    Confirm that the library finds all of the system libraries that it needs:

    ```shell wrap theme={null}
    ldd libfxpkcs11.so
    ```

    <Check>
      Every dependency resolves to a path. For example, `libcrypto.so.3` and `libssl.so.3` resolve to `/lib/64`, and `libstdc++.so.6` and `libgcc_s.so.1` resolve to `/usr/lib/64`. No line shows `file not found`.
    </Check>
  </Step>
</Steps>

## Install the library for Oracle Database

Oracle Database searches the `/opt/oracle/extapi/64/hsm/` directory tree for the HSM PKCS #11 library.

<Warning>
  The `/opt/oracle/extapi/64/hsm/` directory tree must contain exactly **one** library file. If Oracle Database finds more than one library, it cannot open the HSM key store. If you upgrade the Futurex PKCS #11 library, remove the directory of the earlier version.
</Warning>

<Steps>
  <Step>
    Create the library directory. The last part of the path is the library version:

    ```shell wrap theme={null}
    mkdir -p /opt/oracle/extapi/64/hsm/futurex/6.5
    ```
  </Step>

  <Step>
    Copy the library to the directory, and then give the Oracle software owner access to it:

    ```shell wrap theme={null}
    cp /var/tmp/fxpkcs11/libfxpkcs11.so /opt/oracle/extapi/64/hsm/futurex/6.5/
    chmod 755 /opt/oracle/extapi/64/hsm/futurex/6.5/libfxpkcs11.so
    chown -R oracle:oinstall /opt/oracle
    ```
  </Step>

  <Step>
    Confirm that the directory tree contains only one file:

    ```shell wrap theme={null}
    find /opt/oracle/extapi -type f
    ```

    <Check>
      The output shows only `/opt/oracle/extapi/64/hsm/futurex/6.5/libfxpkcs11.so`.
    </Check>
  </Step>
</Steps>

## Place the configuration and TLS files

The Futurex PKCS #11 library reads `/etc/fxpkcs11.cfg` by default. The configuration refers to the TLS files by relative path, so the TLS files must be in the same directory as the configuration.

<Steps>
  <Step>
    Copy the configuration and the TLS files to `/etc`:

    ```shell wrap theme={null}
    cd /var/tmp/fxpkcs11
    cp fxpkcs11.cfg client.p12 client-cert.pem ca-chain.pem CryptoHub*.cer Futurex*.cer /etc/
    ```
  </Step>

  <Step>
    Give the Oracle software owner ownership of the files. The configuration and the PKCS #12 file contain secrets, so only the owner can read them:

    ```shell wrap theme={null}
    cd /etc
    chown oracle:oinstall fxpkcs11.cfg client.p12 client-cert.pem ca-chain.pem CryptoHub*.cer Futurex*.cer
    chmod 600 fxpkcs11.cfg client.p12
    chmod 644 client-cert.pem ca-chain.pem CryptoHub*.cer Futurex*.cer
    ```
  </Step>

  <Step>
    Open `/etc/fxpkcs11.cfg` in a text editor, and then set the log file location:

    ```text title="/etc/fxpkcs11.cfg" theme={null}
    <LOG-FILE> /tmp/fxpkcs11.log </LOG-FILE>
    ```

    The Oracle software owner must be able to write to this location.
  </Step>
</Steps>

## Test the connection to CryptoHub

<Steps>
  <Step>
    Copy the test program to a directory that the Oracle software owner can use:

    ```shell wrap theme={null}
    mkdir -p /export/home/oracle/fxpkcs11
    cp /var/tmp/fxpkcs11/configTest /var/tmp/fxpkcs11/PKCS11Manager /export/home/oracle/fxpkcs11/
    chown -R oracle:oinstall /export/home/oracle/fxpkcs11
    ```
  </Step>

  <Step>
    As the Oracle software owner, run the configuration test:

    ```shell wrap theme={null}
    su - oracle
    cd /export/home/oracle/fxpkcs11
    ./configTest /etc/fxpkcs11.cfg
    ```

    <Check>
      The **Token Info** section shows `Label: Futurex` and a **Serial Number** that matches your CryptoHub. The log file shows `Established connection to HSM` and `FxPKCS11 library version 6.5`.
    </Check>
  </Step>
</Steps>

If the test fails, see [Troubleshooting](./troubleshooting#the-configuration-test-cannot-connect-to-cryptohub).

## Move the PIN to Oracle Database

The `<CRYPTO-OPR-PASS>` value in `fxpkcs11.cfg` is the PIN for the endpoint identity. Oracle Database gives this PIN to the library when it opens the HSM key store, so the configuration file does not need to keep it.

<Steps>
  <Step>
    Copy the `<CRYPTO-OPR-PASS>` value from `/etc/fxpkcs11.cfg`, and then store it in a secure location. This guide calls this value the *CryptoHub endpoint PIN*.
  </Step>

  <Step>
    Comment out the `<CRYPTO-OPR-PASS>` line:

    ```text title="/etc/fxpkcs11.cfg" theme={null}
    # <CRYPTO-OPR-PASS> CRYPTOHUB_ENDPOINT_PIN </CRYPTO-OPR-PASS>
    ```
  </Step>

  <Step>
    Delete the staging directory:

    ```shell wrap theme={null}
    rm -rf /var/tmp/fxpkcs11
    ```
  </Step>
</Steps>

Continue to [Configure Oracle Database for the HSM key store](./configure-oracle-database).