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):
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:
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.
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:
scheme="https" secure="true" SSLEnabled="true"
When you finish making your edits, be sure to restart the “Diplomat MFT 64” service so that the changes take effect.
Diplomat MFT Client, Job Monitor and Scripting Agent
If you plan on using the legacy Diplomat MFT client, Job Monitor Application, or Scripting Agent after you have deployed your own custom SSL certificate file, then you will need to update the “diplomat.keystore” files that exist in the Diplomat MFT installation path (c:\program files\coviant software\diplomat-j) and its “scriptingAgent” subfolder.
These “diplomat.keystore” files ensure secure communication between these applications and the Diplomat MFT server by matching the server-side certificate with the value stored in “diplomat.keystore”. Therefore, if you change the server SSL certificate, these clients will fail to connect until you change the contents of the “diplomat.keystore”.
To do so, you will need to have your certificate and keyfile in a PKCS12 (.pfx or .p12) file format. 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.
Run a Java “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 and navigate into the installation folder, 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 keystore called “customcertificate.keystore” that holds the server certificate for verification by Diplomat Client, Job Monitor, and Scripting Agent.
Now you can delete the previous “diplomat.keystore” and copy this new “customcertificate.keystore” into these paths:
c:\program files\coviant software\diplomat-j\diplomat.keystore c:\program files\coviant software\diplomat-j\scriptingAgent\diplomat.keystore