> ## 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.

# Configure KMES Series 3

> Configuration steps for KMES Series 3 to support Apache HTTPS with PKCS #11.

This section starts with general KMES configurations that enable Apache to integrate with the KMES to store the private key used for HTTPS connections. The second half of this section covers the steps to configure TLS communication between the KMES Series 3 and the Futurex PKCS #11 library that Apache uses to communicate with the KMES.

## Create a role and identity

Perform the following steps to create a new role and identity for Apache on the device and assign the role to the identity that the Futurex PKCS #11 library uses to connect to the KMES:

<Steps>
  <Step>
    Log in to the KMES application interface with the default Admin identities.
  </Step>

  <Step>
    Go to the **Identity Management** > **Roles** menu and select **\[ Add ]**.
  </Step>

  <Step>
    In the **Role Editor** window, specify a name for the role, select the **Hardened** checkbox, and set the number of logins required to **1**.
  </Step>

  <Step>
    On the **Permissions** tab, select the following permissions:

    <table>
      <thead>
        <tr>
          <th><em><strong>Category</strong></em></th>
          <th><em><strong>Permissions</strong></em></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><strong>Certificate Authority</strong></td>
          <td>Add, Export</td>
        </tr>

        <tr>
          <td><strong>Cryptographic Operations</strong></td>
          <td>Sign</td>
        </tr>

        <tr>
          <td><strong>Keys</strong></td>
          <td>Add</td>
        </tr>
      </tbody>
    </table>
  </Step>

  <Step>
    On the **Advanced** tab, set the allowed ports field to **Host API.**
  </Step>

  <Step>
    Select **\[ OK ]** to finish creating the role.
  </Step>

  <Step>
    Go to the **Identity Management**> **Identities** menu, then right-click the pane background and select **Add** > **Client Application.**
  </Step>

  <Step>
    Change the storage type to **HSM** and specify a name for the identity.
  </Step>

  <Step>
    On the **Assigned Roles** tab, select the hardened role that you just created.
  </Step>

  <Step>
    On the **Authentication** tab, select **\[ Add ]** to configure a new credential.
  </Step>

  <Step>
    In the **Configure Credential** window, set the credential type to **Password**, enter a password for the credential, and select **\[ OK ]**.

    <Check>
      The new Password credential now displays with the API Key credential that exists by default.
    </Check>
  </Step>

  <Step>
    Select the API Key credential and select **\[ Remove ]**.
  </Step>

  <Step>
    In the main **Identity Editor** dialog, select \*\*\[ OK ]\*\*\*to save.

    <Check>
      The new identity now displays in the list with the other identities that exist on the device.
    </Check>
  </Step>
</Steps>

## Enable the Host API commands

Because the Futurex PKCS #11 library connects to the Host API port on the KMES, you must determine which Host API commands are eligible for execution by the **FXPKCS11** library. To enable the commands required for the Apache HTTP Server Operation, perform the following steps:

<Steps>
  <Step>
    Go to **Administration** > **Configuration** > **Host API Options** and enable the following commands:

    <table>
      <thead>
        <tr>
          <th><em><strong>Command</strong></em></th>
          <th><em><strong>Description and additional modifiers</strong></em></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><strong>ATKG</strong></td>
          <td>Manipulate HSM trusted asymmetric key group<ul><li><strong>Add</strong>: Add HSM trusted asymmetric key group.</li><li><strong>Modify</strong>: Modify HSM trusted asymmetric key group.</li><li><strong>Delete</strong>: Delete HSM trusted asymmetric key group.</li><li><strong>Get</strong>: Retrieve HSM trusted asymmetric key group.</li></ul></td>
        </tr>

        <tr>
          <td><strong>ECHO</strong></td>
          <td>Communication Test/Retrieve Version</td>
        </tr>

        <tr>
          <td><strong>RAFA</strong></td>
          <td>Filter Issuance Policy</td>
        </tr>

        <tr>
          <td><strong>RAND</strong></td>
          <td>Generate Random Number</td>
        </tr>

        <tr>
          <td><strong>RKCK</strong></td>
          <td>Create HSM Trusted Key</td>
        </tr>

        <tr>
          <td><strong>RKCP</strong></td>
          <td>Get Command Permissions</td>
        </tr>

        <tr>
          <td><strong>RKCS</strong></td>
          <td>Create Symmetric HSM Trusted Key Group</td>
        </tr>

        <tr>
          <td><strong>RKGP</strong></td>
          <td>Export Asymmetric HSM Trusted Key</td>
        </tr>

        <tr>
          <td><strong>RKGS</strong></td>
          <td>Generate Signature</td>
        </tr>

        <tr>
          <td><strong>RKLN</strong></td>
          <td>Lookup Objects</td>
        </tr>

        <tr>
          <td><strong>RKLO</strong></td>
          <td>Login User</td>
        </tr>

        <tr>
          <td><strong>RKPK</strong></td>
          <td>Pop Generated Key</td>
        </tr>

        <tr>
          <td><strong>TIME</strong></td>
          <td>Set Time</td>
        </tr>
      </tbody>
    </table>
  </Step>

  <Step>
    After enabling the preceding commands, select **\[ Save ]**.
  </Step>
</Steps>

## Configure TLS communication

To configure TLS communication between the KMES and PKCS #11 library, you need to  perform the following tasks:

* Create a Certificate Authority
* Create a CSR pair for the System/Host API connection pair
* Sign the System/Host API CSR
* Export the TLS Root CA certificate
* Export the signed System/Host API TLS certificate
* Load the exported TLS certificates into the System/Host API connection pair
* Generate a TLS private key and certificate signing request for the Futurex PKCS #11 library by using OpenSSL
* Sign the Certificate Signing Request (CSR) for the FXPKCS11 Library
* Export the signed FXPKCS11 TLS certificate

The following sections detail these task procedures.

### Create a Certificate Authority

<Steps>
  <Step>
    Go to the **PKI**> **Certificate Authorities** menu and select **\[ Add CA ]** at the bottom of the window.
  </Step>

  <Step>
    In the **Certificate Authority** dialog, enter a name for the certificate container, leave all other fields set to the default values, and select **\[ OK ]**.
  </Step>

  <Step>
    Right-click the certificate container that you created and select **Add Certificate** > **New Certificate.**
  </Step>

  <Step>
    On the **Subject DN** tab, select the **Classic** preset and set a **Common Name** for the certificate, such as `System TLS CA Root`.
  </Step>

  <Step>
    On the **Basic Info** tab, leave all fields set to the default values.
  </Step>

  <Step>
    On the **V3 Extensions** tab, select the **Certificate Authority** profile and select
    **\[ OK ]**.

    <Check>
      The root CA certificate now displays under the previously created certificate container.
    </Check>
  </Step>
</Steps>

### Generate a CSR

Perform the following steps to generate a CSR for the System/Host API connection pair:

<Steps>
  <Step>
    Go to **Administration**> **Configuration**> **Network Options**.
  </Step>

  <Step>
    In the **Network Options** dialog, go to the **TLS/SSL Settings** tab.
  </Step>

  <Step>
    Under the **System/Host API** connection pair, uncheck the **Use Futurex Certificates** checkbox and select **\[ Edit ]** next to the PKI keys in the **User Certificates** section.
  </Step>

  <Step>
    In the **Application Public Keys** window, select **\[ Generate ]**.
  </Step>

  <Step>
    When the *SSL will not be functional until new certificates are imported* warning displays, select **\[ Yes ]** to continue.
  </Step>

  <Step>
    In the **PKI Parameters** window, leave the default settings and select **\[ OK ]**.
  </Step>

  <Step>
    When you see that a PKI Key Pair is loaded in the **Application Public Keys** dialog, select **\[ Request ]**.
  </Step>

  <Step>
    On the **Subject DN** tab, set a **Common Name** for the certificate, such as `KMES`.
  </Step>

  <Step>
    On the **V3 Extensions** tab, select the **TLS Server Certificate** profile.
  </Step>

  <Step>
    On the **PKCS #10 Info** tab, select a save location for the CSR and select **\[ OK ].**
  </Step>

  <Step>
    When the save successful message displays, select **\[ OK ].**
  </Step>

  <Step>
    Select **\[ OK ]** again to save the **Application Public Keys** settings.

    <Check>
      The main Network Options dialog now shows Loaded next to PKI Keys for the System/Host API connection pair.
    </Check>
  </Step>
</Steps>

### Sign the CSR

Perform the following steps to sign the System/Host API CSR:

<Steps>
  <Step>
    Go to the **PKI**> **Certificate Authorities** menu.
  </Step>

  <Step>
    Right-click the **System TLS CA Root** certificate created previously and select **Add Certificate** >
    **From Request.**
  </Step>

  <Step>
    In the file browser, select the CSR generated for the System/Host API connection pair.
  </Step>

  <Step>
    After it loads, you don't need to modify any certificate settings. Select **\[ OK ]**.

    <Check>
      The signed System/Host API TLS certificate should now show under the TLS root CA certificate on the Certificate Authorities page.
    </Check>
  </Step>
</Steps>

### Export the certificate

Perform the following steps to export the TLS Root CA certificate:

<Steps>
  <Step>
    Go to the **PKI** > **Certificate Authorities** menu.
  </Step>

  <Step>
    Right-click the **System TLS CA Root** certificate and select **Export**> **Certificate(s).**
  </Step>

  <Step>
    In the **Export Certificate** window, select the **PEM** encoding and select **\[** **Browse ]**.
  </Step>

  <Step>
    In the file browser, navigate to the location where you want to save the TLS root CA certificate. Specify a name for the file and select **\[ Open ]**.
  </Step>

  <Step>
    Select **\[ OK ]**.

    <Check>
      A message box says that the PEM file was successfully written to the location that you specified.
    </Check>
  </Step>
</Steps>

### Export the TLS certificate

Perform the following steps to export the signed System/Host API TLS certificate:

<Steps>
  <Step>
    Go to the **PKI**> **Certificate Authorities** menu.
  </Step>

  <Step>
    Right-click the KMES certificate and select **Export** > **Certificates(s)**.
  </Step>

  <Step>
    In the **Export Certificate** dialog, select the **PEM** encoding and select **\[** **Browse ]**.
  </Step>

  <Step>
    In the file browser, go to the location where you want to save the signed System/Host API TLS certificate. Specify a name for the file and select **\[ Open ]**.
  </Step>

  <Step>
    Select **\[ OK ]**.

    <Check>
      A message box says that the PEM file was successfully written to the location that you specified.
    </Check>
  </Step>
</Steps>

### Load the exported certificates

Perform the following steps to load the exported TLS certificates into the System/Host API connection pair:

<Steps>
  <Step>
    Go to **Administration**> **Configuration**> **Network Options**.
  </Step>

  <Step>
    In the **Network Options** dialog, go to the **TLS/SSL Settings** tab.
  </Step>

  <Step>
    Select **\[ Edit ]** next to Certificates in the **User Certificates** section.
  </Step>

  <Step>
    Right-click the **System/Host API SSL CA** X.509 certificate container and then select **\[ Import ].**
  </Step>

  <Step>
    Select **\[ Add ]** at the bottom of the **Import Certificates** window.
  </Step>

  <Step>
    In the file browser, select the TLS Root CA certificate and the signed System/Host API TLS certificate, and select **\[ Open ]**.

    <Check>
      The certificate chain appears in the Verified section.
    </Check>
  </Step>

  <Step>
    Select **\[ OK ]** to save the changes.

    <Check>
      In the Network Options window, the System/Host API connection pair now shows Signed loaded next to Certificates in the User Certificates section
    </Check>
  </Step>

  <Step>
    Select **\[ OK  ]** to save and exit the **Network Options** window.
  </Step>
</Steps>

### Generate a private key and CSR

Execute the following commands from a terminal application with OpenSSL to generate a TLS private key and certificate signing request (CSR) for the Futurex PKCS #11 library:

<Steps>
  <Step>
    Open a terminal and run the following command to generate a TLS private key for the **FXPKCS11** library:

    ```shell expandable lines wrap title="Shell" theme={null}
    $ openssl genrsa -out fxpkcs11_tls_privatekey.pem 2048
    ```
  </Step>

  <Step>
    Run the following command to generate a CSR for the **FXPKCS11** library:

    ```shell expandable lines wrap title="Shell" theme={null}
    $ openssl req -new -key fxpkcs11_tls_privatekey.pem -out fxpkcs11_tls_cert_req.pem -days 365
    ```

    It prompts you to enter certificate information. The CSR outputs to a file named `fxpkcs11_tls_cert_req.pem` in the same directory where you ran the command.
  </Step>

  <Step>
    Move or copy the CSR file to the storage medium configured on the KMES.
  </Step>
</Steps>

### Sign the CSR

Perform the following steps to sign the CSR for the **FXPKCS11** Library:

<Steps>
  <Step>
    Go to the **PKI**> **Certificate Authorities** menu.
  </Step>

  <Step>
    Right-click the **System TLS CA Root** certificate and select **Add Certificate** > **From Request**.
  </Step>

  <Step>
    In the file browser, locate and select the **FXPKCS11** CSR. Certificate information populates in the **Create X.509 From CSR** window.
  </Step>

  <Step>
    On the **Subject DN** tab, change the preset drop-down option to **Classic**, and set a Common Name for the certificate, such as `FXPKCS11`.
  </Step>

  <Step>
    On the **Basic Info** tab, leave all settings set to the default values.
  </Step>

  <Step>
    On the **V3 Extensions** tab, select the **TLS Client Certificate** profile, and then select **\[ OK ].**

    <Check>
      The signed FXPKCS11 certificate now displays in the list under the TLS Root Certificate.
    </Check>
  </Step>
</Steps>

### Export the signed certificate

Perform the following steps to export the signed **FXPKCS11** TLS certificate:

<Steps>
  <Step>
    Go to the **PKI** > **Certificate Authorities** menu.
  </Step>

  <Step>
    Right-click the **FXPKCS11** certificate and select **Export**> **Certificate(s).**
  </Step>

  <Step>
    In the **Export Certificate** dialog, change the **PEM** encoding and select **\[ Browse ]**.
  </Step>

  <Step>
    In the file browser, go to the location where you want to save the **FXPKCS11** TLS certificate. Specify a name for the file and select **\[ Open ]**.
  </Step>

  <Step>
    Select **\[ OK ]**.

    <Check>
      A Message box says that the PEM file was successfully written to the location that you specified.
    </Check>
  </Step>

  <Step>
    Move both the signed **FXPKCS11** TLS certificate and the TLS Root CA certificate to the computer that hosts the Apache HTTP Server instance.

    The next section shows how to configure and use them for TLS communication with the KMES Series 3.
  </Step>
</Steps>