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

> Procedures to configure KMES Series 3 settings and TLS for integration with vSEC:CMS.

This section starts with general configurations you must make on the KMES to enable Versasec vSEC:CMS to integrate with the KMES for storing the master key(s) used when performing administration key operations with the vSEC:CMS, such as registering a credential or PIN unblock operations. Then, it covers the necessary steps to configure TLS communication between the KMES and the vSEC:CMS instance.

## Configure general KMES settings  for integration with vSEC:CMS

Perform the following tasks to configure the KMES Series 3 for communication with SignTool:

1. Create a Verasec role and identity with the correct assigned permissions.
2. Enable Host API commands.

The following sections show you how to complete these tasks.

### Create a role and identity

Perform the following steps to create a new role and identity for vSEC on the KMES Series 3 with the required permissions. A later section shows you how to configure them in the Futurex PKCS #11 configuration file.

<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 ]** at the bottom of the page.
  </Step>

  <Step>
    On the **Info** tab of the **Role Editor** window, specify a **name** for the role and set the number of **Logins** **Required** to `1`.
  </Step>

  <Step>
    On the **Permissions** tab, enable 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>Cryptographic Operations</strong></td>
          <td>Sign, Verify, Encrypt, Decrypt</td>
        </tr>

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

  <Step>
    On the **Advanced** tab, configure **Allowed** **Ports** to **Host API** only
  </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>
    On the **Info** tab of the **Identity Editor** window, select **Application** for the storage location and specify a **name** for the identity.
  </Step>

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

  <Step>
    On the **Authentication** tab, configure the **password**.
  </Step>

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

### Enable the Host API commands

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 the **FXPKCS11** library. To enable the eHost API commands required for vSEC:CMS operation, 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** and enable the following commands:

    <table>
      <thead>
        <tr>
          <th><em><strong>Command</strong></em></th>
          <th><em><strong>Description or subcommand (if applicable)</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>RKCP</strong></td>
          <td>Get Command Permissions<ul><li><strong>get</strong>: Retrieve enabled commands</li><li><strong>modify</strong>: Update enabled commands</li></ul></td>
        </tr>

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

        <tr>
          <td><strong>RKDP</strong></td>
          <td>Delete Asymmetric HSM Trusted Key</td>
        </tr>

        <tr>
          <td><strong>RKED</strong></td>
          <td>Encrypt or Decrypt Data</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>RKRC</strong></td>
          <td>Get HSM Trusted Key</td>
        </tr>

        <tr>
          <td><strong>RKRU</strong></td>
          <td>RSA unwrap the symmetric key</td>
        </tr>

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

  <Step>
    Select **\[ Save ]** to finish.
  </Step>
</Steps>

## Configure TLS communication

Perform the following tasks to configure TLS communication between the KMES Series 3 and the vSEC:CMS instance:

1. Create a Certificate Authority.
2. Generate a CSR for the System/Host API connection pair.
3. Sign the System/Host API CSR.
4. Export the Root CA certificate.
5. Export the signed System/Host API TLS certificate.
6. Load the exported certificates into the System/Host API connection pair.
7. Issue a client certificate for vSEC:CMS.
8. Export the vSEC:CMS certificate as a PKCS #12 file.

The following sections describe how to perform these tasks.

### Create a Certificate Authority

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>
    Go to **PKI** > **Certificate** **Authorities** 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 select **\[ OK ]**.

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

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

  <Step>
    On 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 of the default values set.
  </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** window, 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 **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 fields set to the default values and select **\[ OK ]**.

    <Check>
      The Application Public Keys window now shows that a PKI Key Pair is Loaded.
    </Check>
  </Step>

  <Step>
    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 notified that *the certificate signing request was successfully written to the file location that was selected*, select **\[ OK ]**\*.
  </Step>

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

    <Check>
      The main Network Options window 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 **PKI** > **Certificate** **Authorities**.
  </Step>

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

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

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

    <Check>
      The signed System/Host API certificate now shows 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 location where you want 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 the location that you specified.
    </Check>
  </Step>
</Steps>

### Export the Host API 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 **System/Host API TLS** 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 location where you want to save the System/Host API 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 the location that you specified.
    </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>
    Under the **System/Host API** connection pair, 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 select **\[ Import ]**.
  </Step>

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

  <Step>
    In the file browser, select both the root CA certificate and the signed System/Host API certificate, and select **\[ Open ]**.
  </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>

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

### Issue a client certificate

Perform the following steps to issue a client certificate for vSEC:CMS. A later section shows how to configure it in the Futurex PKCS #11 configuration file.

<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>
    On the **Subject DN** tab, set a **Common Name** for the certificate, such as `vSEC`.
  </Step>

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

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

    <Check>
      The vSEC certificate now displays under the System TLS CA Root certificate.
    </Check>
  </Step>
</Steps>

#### Export the vSEC:CMS certificate

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

Perform the following steps to export the vSEC:CMS certificate as PKCS #12 file:

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

  <Step>
    Right-click the vSEC certificate and select **Export** > **PKCS12**.
  </Step>

  <Step>
    Select the **Export Selected** option, specify a unique name for the export file, and select **\[ Next ]**.
  </Step>

  <Step>
    Choose and enter a file password and select **\[ Next ]**.
  </Step>

  <Step>
    Select **\[ Finish ]** to initiate the export.
  </Step>

  <Step>
    Move both the **vSEC** certificate and the Root CA certificate that was exported in the **Export the Root CA certificate** section to the computer that runs the vSEC:CMS instance.

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