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

> Procedural guide to configure KMES Series 3 for SSH key offloading integration.

This section covers the necessary KMES Series 3 configurations for this integration.

## Configure the Futurex PKCS #11 integration

This section covers general configurations you must make on the KMES Series 3 to enable the Futurex PKCS #11 module to integrate for SSH Key Offloading.

### Create a role and identity

Perform the following steps to create a new role and identity for SSH on the KMES Series 3:

<Note>
  A later section configures the identity name and password in the Futurex PKCS #11 configuration file.
</Note>

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

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

  <Step>
    In the **Role** **Editor** window, configure the following settings:

    * Specify a **name** for the role.
    * Set the number of logins required to **1.**
    * Go to the **Advanced** tab.
    * Allow authentication to the **Host** **API** port only.
    * Leave all other fields set to the default values.
  </Step>

  <Step>
    Go to the **Permissions** tab and select the following permissions:

    <table>
      <thead>
        <tr>
          <th><em><strong>Permission</strong></em></th>
          <th><em><strong>Subpermission</strong></em> </th>
        </tr>
      </thead>

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

        <tr>
          <td><strong>Keys</strong></td>
          <td>Top-level permission only</td>
        </tr>

        <tr>
          <td><strong>Signing Approval</strong></td>
          <td>Add</td>
        </tr>
      </tbody>
    </table>
  </Step>

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

  <Step>
    Go to **Identity** **Management** > **Identities**, right-click anywhere in the window, and select **Add** > **Client** **Application**.
  </Step>

  <Step>
    In the **Info** tab of the **Identity** **Editor** window, select **Application** for the storage location and specify a **name** for the identity, such as `crypto1`.
  </Step>

  <Step>
    In the **Assigned** **Roles** tab, select the role you created in the previous section.
  </Step>

  <Step>
    Under **Authentication**, select the **API Key** mechanism and then **\[ Remove ]**. Then select **\[ Add ]** and set the type to **Password**. Set the password for the identity and then select **\[ OK ]** to finish.

    <Note>
      A later section configures the password in the Futurex PKCS #11 configuration file.
    </Note>
  </Step>

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

### Enable the Host API commands required for PKCS #11

Because the Futurex PKCS #11 library connects to the Host API port on the KMES, you must define which Host API commands to enable for execution by the **FXPKCS11** library. To set the allowed commands, complete the following steps:

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

  <Step>
    Go to **Administration** > **Configuration** > **Host API Options**, select the **All** preset to enable all commands, and then select **\[ Save ]**.
  </Step>
</Steps>

## Configure TLS communication

This section covers the steps required to configure TLS communication between the KMES and the Futurex PKCS #11 library.

#### Create a CA

Perform the following steps to create a certificate authority (CA):

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

  <Step>
    Select **PKI** > **Certificate** **Authorities** in the left menu, and select **\[ Add CA ]** at the bottom of the page.
  </Step>

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

    <Check>
      The new certificate container now displays in the Certificate Authorities menu.
    </Check>
  </Step>

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

  <Step>
    In the **Subject** **DN** tab, 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>
    In 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** window, go to the **TLS/SSL Settings** tab.
  </Step>

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

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

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

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

    <Check>
      A message states that a PKI Key Pair is loaded in the Application Public Keys window.
    </Check>
  </Step>

  <Step>
    Select **\[ Request ]**.
  </Step>

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

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

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

    <Check>
      A message states that the certificate signing request was successfully written to the file location selected.
    </Check>
  </Step>

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

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

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

#### Sign the System/Host API CSR

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

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

  <Step>
    Right-click on the root CA certificate you created for this integration, and select **Add** **Certificate** > **From** **Request**.
  </Step>

  <Step>
    Select the CSR generated for the System/Host API connection pair in the file browser.
  </Step>

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

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

#### Export the Root CA certificate

Perform the following steps to export the Root CA certificate:

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

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

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

  <Step>
    In the file browser, go to the directory to save the Root CA certificate. Specify a name for the file and select **\[ Open ]**.
  </Step>

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

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

#### Export the signed certificate

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

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

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

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

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

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

    <Check>
      A message states that the PEM file was successfully written to your specified location.
    </Check>
  </Step>
</Steps>

#### Load the exported certificates

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

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

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

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

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

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

  <Step>
    Select the **root CA** certificate and the signed **System/Host API** certificate in the file browser and select **\[ Open ]**.

    <Check>
      The certificate chain displays in the Verified section of the window.
    </Check>
  </Step>

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

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

#### Issue a client certificate

Perform the following steps to issue a client certificate for the Futurex PKCS #11 module:

<Note>
  You configure the client certificate created here in the Futurex PKCS #11 configuration file.
</Note>

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

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

  <Step>
    In the **Subject** **DN** tab, set a **Common** **Name** for the certificate.
  </Step>

  <Step>
    Leave all settings in the **Basic** **Info** tab set to the default values.
  </Step>

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

    <Check>
      The PKCS #11 client certificate will now be listed under the System TLS CA Root certificate.
    </Check>
  </Step>
</Steps>

#### Export the client certificate

Perform the following steps to export the client certificate as a PKCS #12 file:

<Note>
  To perform the following steps, go to Administration > Configuration > Options and enable the Allow export of certificates using password option.
</Note>

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

  <Step>
    Right-click the PKCS #11 client certificate, and select **Export** > **PKCS12**.
  </Step>

  <Step>
    Set a PKCS #12 password, leave **Export Selected Certificate with Parents** selected, and select **\[ Next ]**.
  </Step>

  <Step>
    Select the storage device to use and select **\[ OK ]**.
  </Step>

  <Step>
    Enter a name for the file, select the location where you want to save it, and select **\[ Open ]**.

    <Note>
      You must move the FXPKCS11 Client certificate to the computer where the Futurex PKCS #11 module is installed. A later section configures it in the FXPKCS11 configuration file and uses it for TLS communication with the KMES Series 3.
    </Note>
  </Step>
</Steps>

### General KMES configurations for SSH key offloading

This section covers general KMESSSH key offloading configuration.

#### Create a CA for the SSH key pair

Perform the following steps to create a CA for the SSH key pair:

<Steps>
  <Step>
    Go to **PKI**> **Certificate Authorities**, then select **\[ Add CA ]** at the bottom of the page.
  </Step>

  <Step>
    Set the name of the certificate container, such as `SSH Key Offloading`, and set the Owner group to the role you created for this integration. Then select **\[ OK ]**.
  </Step>

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

  <Step>
    In the **Subject DN** tab of the **Create X.509 Certificate** window, select the **Classic Preset** in the drop-down list and specify `SSH` as the certificate **Common Name**.
  </Step>

  <Step>
    In the **Basic Info** tab, you can leave the default values set.
  </Step>

  <Step>
    In the **V3 Extensions** tab, leave the default value of **None** in the profile drop-down menu.
  </Step>

  <Step>
    Select **\[ OK ]** to finish creating the SSH client key pair.
  </Step>
</Steps>

#### Create an Approval Group

Perform the following steps to create an Approval Group for PKI Signing:

<Steps>
  <Step>
    Go to **PKI** >
    **Signing Workflow** and select **\[ Add Approval Group ]** at the bottom of the page.
  </Step>

  <Step>
    Specify `SSH` as the **Name** of the Approval Group and select **\[ OK ]**.
  </Step>

  <Step>
    Right-click on the newly created Approval Group and select **Permission**.
  </Step>

  <Step>
    Give the role created for SSH Key Offloading the **Use** permission, and select **\[ OK ]**.
  </Step>
</Steps>

#### Add an Issuance Policy

Perform the following steps to add an Issuance Policy to the SSH certificate:

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

  <Step>
    Right-click the SSH certificate and select **Issuance Policy** > **Add**.
  </Step>

  <Step>
    In the **Basic Info** tab, set **Approvals** to **0** and **Allowed Hashes** to **SHA-512**.
  </Step>

  <Step>
    In the **X.509** tab, set the **Default Approval Group** to **SSH**.
  </Step>

  <Step>
    In the **Object Signing** tab, select the **Allow Object signing** checkbox.
  </Step>

  <Step>
    Select **\[ OK ]** to apply the Issuance Policy to the SSH client certificate.
  </Step>

  <Step>
    Right-click the SSH certificate and select **Change Security Usage**.
  </Step>

  <Step>
    In the **Security Usage** drop-down menu, select **Anonymous Signing**.
  </Step>

  <Step>
    Select **\[ OK ]** to apply the change.
  </Step>
</Steps>

#### Export the public key

Perform the following steps to export the public key for the SSH key pair:

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

  <Step>
    Right-click on the SSH certificate and select **Export** > **Public Key(s)**.
  </Step>

  <Step>
    Browse for where you want to save the file and select **\[ Choose ]**.
  </Step>

  <Step>
    Select **\[ OK ]** in the dialog box that says, *Successfully exported certificate public key(s)*.
  </Step>
</Steps>