1. Home
  2. User Guides
  3. Diplomat MFT 9.0
  4. Diplomat MFT Web Admin SSL Certificate
  1. Home
  2. Installation and Set-up
  3. Diplomat MFT Web Admin SSL Certificate

Diplomat MFT Web Admin SSL Certificate

Overview

When you install Diplomat MFT v9 or higher, or when you upgrade from a version of Diplomat MFT older than v9, the installation process will create a self-signed ssl certificate for your Diplomat MFT Server to use. By creating a unique certificate for each installation, we help to ensure the security of our customers by allowing their browsers to trust only that one self-signed certificate that is specific to their instance of Diplomat MFT.

However, for some customers the use of a self-signed certificate is not secure enough, either by policy or practice, and therefore it might be necessary to install a different SSL certifcate on their Diplomat MFT Server. This article describes how to install your own SSL certificate for Diplomat MFT Server.

Default Installation Behavior

After you install (or upgrade) Diplomat MFT v9 or higher, you will use a web browser to visit the page to monitor and configure the Diplomat MFT Server. This url is “https://localhost:8080/” for a paid installation, and “https://localhost:8081/” for a trial installation. When you visit this page, your browser will inform you that the server has a security issue due to the self-signed certificate. This is what the browser will look like (the actual details vary by browser, but the concepts are the same):

self-signed certificate warning

To proceed to the Diplomat MFT web admin, click on the “Advanced” button, then the “proceed to localhost” link seen at the bottom of the following screenshot:

advanced ssl cert warning

Remote Agent and Scripting Agent with default SSL Certificate

Diplomat’s Remote Agent is designed to run on computers separate from the Diplomat MFT server in order to act as an endpoint for Diplomat MFT’s automated processes. The Scripting Agent provides a mechanism for invoking those automated processes to run, and it may be run on the Diplomat MFT server computer itself or on other systems to enable futher integration.

In order to allow communications from Diplomat MFT to a Remote Agent installation or a Scripting Agent installation to communicate with Diplomat MFT, you will need copy the diplomat.keystore file from Diplomat MFT to the Remote Agent or Scripting Agent. On the Diplomat MFT server computer, that file to copy is stored by default in C:\Program Files\Coviant Software\Diplomat-j.

Remote Agent: Stop the “Diplomat Remote Agent 64” service and place the keystore file by default in C:\Program Files\Coviant Software\Diplomat-RemoteAgent\tomcatWebserver\conf, overwriting any prior version of the file.

Scripting Agent: Place the keystore file by default in C:\Program Files\Coviant Software\Diplomat-j\scriptingAgent, overwriting any prior version of the file.

Changing the Diplomat MFT SSL Certificate

The installation of Diplomat MFT places the self-signed certificate as a KEY and CERT file located in this folder (replace “diplomat-j” with “diplomat-trial” for a trial installation):

c:\program files\coviant software\diplomat-j\tomcatWebserver\conf\diplomat.certificate.pem

 c:\program files\coviant software\diplomat-j\tomcatWebserver\conf\diplomat.key.pem 

If you wish to use your own certificate, make sure the certificate and key are in PEM (base64) encoded X509 format, and place the file(s) into the same folder. If you need to include the intermediate CA authority files, place this file (or files) into the same folder.

You will need to generate a Certificate Signing Request (CSR) in order to create a signed certificate to install on Diplomat MFT. Here is a guide to walk you through that process using tools built into the Windows OS:

https://knowledge.digicert.com/solution/SO29005.html

Then, edit the file “server.xml” found in this same folder. Locate the lines that point to “diplomat.certificate.pem” and “diplomat.key.pem” and replace them with the filenames of your certificate and key file, respectively.

Change the value of “SSLPassword” to match the password you have used to protect your certificate’s key file (or leave as “” if there is no password protecting the key file).

If you need to include the intermediate certificate bundle, add the another entry for “SSLCACertificateFile” that points to your intermediate bundle file.

Here is what a server.xml might look like with your own certificate files in place, using some fictitious but obvious file names:

<Connector port="8080"
   protocol="HTTP/1.1"
   maxThreads="150"
   scheme="https" secure="true" SSLEnabled="true"
   clientAuth="false" sslProtocol="TLS"
   SSLCertificateFile="conf/mycustomcertificate.pem"
   SSLCertificateKeyFile="conf/mycustomkey.pem"
    SSLCACertificateFile="conf/mycustomintermediatebundle.pem"
   SSLVerifyClient="none"
   SSLPassword="secretpassword"
   SSLProtocol="TLSv1.1+TLSv1.2"
   SSLCipherSuite="ECDHE-RSA-CHACHA20-POLY1305,
        ECDHE-RSA-AES128-GCM-SHA256,
        ECDHE-RSA-AES256-GCM-SHA384,
        ECDHE-RSA-AES256-SHA384,
        DHE-RSA-AES128-GCM-SHA256, 
        TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,
        TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA, />

When you finish making your edits, be sure to restart the “Diplomat MFT 64” service so that the changes take effect.

Remote Agent and Scripting Agent with Custom SSL Certificate

If you have deployed your own custom SSL certificate, then you will need to update the diplomat.keystore file that exist in the Diplomat MFT installation path (by default C:\Program Files\Coviant Software\Diplomat-j), its scriptingAgent subfolder, and any Remote Agent and Scripting Agent installations on other systems.

The diplomat.keystore file ensures secure communication between these applications and the Diplomat MFT server by matching the server-side certificate with the value stored in the diplomat.keystore file. Therefore, if you change the server certificate, these clients will fail to connect until you create and deploy a new diplomat.keystore file that contains the updated certificate.

Your SSL certificate and private key must be properly formatted in a PKCS12 (.pfx or .p12) file. If your SSL certificate provider does not offer this format for you, please use OpenSSL to perform the conversion or contact our customer support team for help.

Use the “keytool” command to create a new keystore file that contains the new certificate that you deployed onto the Diplomat MFT server. Open a command prompt, navigate into the installation folder, and then type this command:

"jre\bin\keytool.exe" -importkeystore -srcstoretype PKCS12 -srcstorepass <<pkcs12 password>> -srckeystore mycustomcertificate.pfx -deststoretype JKS -deststorepass changeit -destkeystore customcertificate.keystore

This will create a new file called customcertificate.keystore that holds the server certificate for verification by Remote Agent and Scripting Agent installations. Delete the previous diplomat.keystore file from the installation folder and rename the new customcertificate.keystore to diplomat.keystore in its place. Copy the new file to the scriptingAgent subfolder, overwring any prior version of the file.

You can now also deploy your new diplomat.keystore file to other systems running the Remote Agent or Scripting Agent.

Remote Agent: Stop the “Diplomat Remote Agent 64” service and place the keystore file by default in C:\Program Files\Coviant Software\Diplomat-RemoteAgent\tomcatWebserver\conf, overwriting any prior version of the file.

Scripting Agent: Place the keystore file by default in C:\Program Files\Coviant Software\Diplomat-j\scriptingAgent, overwriting any prior version of the file.

Updated on November 2, 2022

Was this article helpful?

Related Articles