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

> Instructions to configure KMES TLS and general settings for Jenkins code signing integration.

This section shows you how to configure TLS communication between the KMES Series 3 and the Jenkins instance and then covers general KMES configurations for the KMES to provide Jenkins code-signing functionality.

## Configure TLS communication

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

1. Create a certificate authority (CA).
2. Generate a CSR for the System/Host API connection pair.
3. Sign the System/Host API CSR.
4. Export the Root CA and signed System/Host API TLS certificate.
5. Load the exported certificates into the System/Host API connection pair.
6. Generate a signed client certificate for the Jenkins instance.
7. Allow export of certificates by using passwords.
8. Export the signed Jenkins certificate as a PKCS #12 file.

The following sections describe how to perform these tasks.

### Create a CA

Perform the following steps to create a 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 set to the default values, and select **\[ OK ]**.

    <Check>
      The certificate container that 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 the settings 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** 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 all fields set to the default values and select **\[ OK ]**.

    <Check>
      You see that a PKI Key Pair is loaded in the Application Public Keys window.
    </Check>
  </Step>

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

  <Step>
    On the **Subject** **DN** tab, you can leave the default System/Host API value set in the **Common Name** field, or you can change it to a different value.
  </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 prompted 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 menu under the System/Host API connection pair now shows Loaded next to PKI Keys.
    </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 root CA certificate you created and select **Add** **Certificate** > **From** **Request**.
  </Step>

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

  <Step>
    After it loads, you don't need to modify any settings for the certificate. 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 and certificates

Perform the following steps to export the Root CA and signed System/Host API certificates:

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

  <Step>
    Change the encoding to **PEM** and select **\[ Browse ]**. Specify a location and name for the export file.
  </Step>

  <Step>
    When prompted that *the file was successfully written to the location that was selected*, select **\[ OK ]**.
  </Step>

  <Step>
    Right-click the signed System/Host API certificate and select **Export** > **Certificate(s)**.
  </Step>

  <Step>
    Change the encoding to **PEM** and select **\[ Browse ]**. Specify a location and name for the export file.
  </Step>

  <Step>
    When prompted that *the file was successfully written to the location that was selected*, select **\[ OK ]**.
  </Step>
</Steps>

### Load the 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 ]**.

    <Check>
      The certificate chain appears in 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>

### Generate a certificate

Perform the following steps to generate a signed certificate for the Jenkins instance:

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

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

  <Step>
    On the **Subject** **DN** tab, set a **Common Name** for the certificate, such as `Jenkins`.
  </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 signed Jenkins certificate now displays under the root CA certificate.
    </Check>
  </Step>
</Steps>

#### Allow export of certificates

Perform the following steps to configure the  **allow export of certificates by using passwords** function:

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

  <Step>
    Select the checkbox next to the menu option **Allow export of certificates using passwords**.
  </Step>

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

#### Export the certificate

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

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

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

  <Step>
    Select **\[ Set Password ]**, enter a password for the PKCS #12 file, and select **\[ Save ]**.
  </Step>

  <Step>
    In the **Export** **Certificates** window, select **Export** **Selected** **Certificate** **with** **Parents** under **Export Options**, and select **\[ Next ]**.
  </Step>

  <Step>
    Specify a name for the PKCS #12 export file and select **\[ Open ]**.

    <Check>
      A message box states that the PKCS #12 certificate export was successful.
    </Check>
  </Step>
</Steps>

## Configure general KMES settings

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

1. Enable Host API commands.
2. Create a Jenkins role with the required permissions.
3. Create a Jenkins identity with the correct assigned roles.
4. Create a signing approval group and give it appropriate permissions.
5. Create a Jenkins code signing certificate.
6. Apply an issuance policy to the Jenkins code signing certificate.

The following sections show you how to complete these tasks.

### Enable the API commands

Perform the following steps to enable the required Host API commands:

<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</strong></em></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><strong>RAFA</strong></td>
          <td>Enumerate issuance policies</td>
        </tr>

        <tr>
          <td><strong>RAGA</strong></td>
          <td>Retrieve issuance policy details</td>
        </tr>

        <tr>
          <td><strong>RAGZ</strong></td>
          <td>Retrieve Request (Authenticode)</td>
        </tr>

        <tr>
          <td><strong>RAUZ</strong></td>
          <td>Upload Request (Authenticode)</td>
        </tr>

        <tr>
          <td><strong>RAGJ</strong></td>
          <td>Retrieve Request (JAR)</td>
        </tr>

        <tr>
          <td><strong>RAUJ</strong></td>
          <td>Upload Request (JAR)</td>
        </tr>

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

        <tr>
          <td><strong>RAGO</strong></td>
          <td>Retrieve Request (Hash Signing)</td>
        </tr>

        <tr>
          <td><strong>RAUO</strong></td>
          <td>Upload Request (Hash Signing)</td>
        </tr>
      </tbody>
    </table>
  </Step>

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

### Create a Jenkins role

Perform the following steps to create a Jenkins role with the required permissions:

<Steps>
  <Step>
    Go to **Identity Management** > **Roles**, then select **\[ Add ]** at the bottom of the page.
  </Step>

  <Step>
    On the **Info** tab, specify a name for the role, such as `Jenkins`. Set the **Type** to **Application**, the **Role** **Class** to **Principal**, and **Logins** **Required** to `1`.
  </Step>

  <Step>
    On the **Permissions** tab, 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</strong> <strong>Authority</strong></td>
          <td>Export Clear Key, Upload</td>
        </tr>
      </tbody>
    </table>
  </Step>

  <Step>
    On the **Advanced** tab, select only **Host API** for **Allowed** **Ports**.
  </Step>

  <Step>
    Select **\[ OK ]** to save and finish.
  </Step>
</Steps>

### Create a Jenkins identity

Perform the following steps to create a Jenkins identity with the correct assigned roles:

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

  <Step>
    On the **Info** tab, select **Application** for the storage type and specify a name for the identity.
  </Step>

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

  <Step>
    On the **Authentication** tab, remove the API key mechanism, add the password mechanism, and set your password.
  </Step>

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

### Create a signing approval group

Perform the following steps to create a signing approval group and give it appropriate permissions:

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

  <Step>
    Set a name for the approval group, such as `Jenkins`, and select **\[ OK ]** to save.
  </Step>

  <Step>
    Right-click the **Jenkins** approval group you just created and select **\[ Permission ]**.
  </Step>

  <Step>
    Select the **Show all roles and permissions** checkbox, grant the **Jenkins** role the **Use** permission, and select **\[ OK ]**\*.
  </Step>
</Steps>

### Create a Jenkins code signing certificate

Perform the following steps to  create a Jenkins code signing certificate:

<Steps>
  <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**, such as `Jenkins Code Signing CA`. Set the owner of the CA to the Jenkins role and select **\[ OK ]**\*.

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

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

  <Step>
    On the **Subject** **DN** tab, set a **Common Name** for the certificate, such as `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 **Code Signing Certificate** profile and select **\[ OK ]**.

    <Check>
      The Root Jenkins code signing certificate displays under the Jenkins certificate container.
    </Check>
  </Step>
</Steps>

#### Apply an issuance policy

Perform the following steps to  apply an issuance policy to the Jenkins code signing certificate:

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

  <Step>
    Right-click the root certificate within the Jenkins certificate container and select **Issuance Policy** > **Add**.
  </Step>

  <Step>
    On the **Basic** **Info** tab, make the following changes:

    * (Optional) Specify an **Alias**.
    * Set **Approvals** to `1`. Setting approvals to `0` allows anonymous signing.
    * Select any hashes that you want to allow.
  </Step>

  <Step>
    On the **X.509** tab, set the default approval group to **Jenkins**.
  </Step>

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

  <Step>
    Select **\[ OK ]** to apply the issuance policy to the Root Jenkins code signing certificate.
  </Step>
</Steps>