Custom SSL Certificate setup instructions

From 360Works Product Documentation Wiki
(Difference between revisions)
Jump to: navigation, search
(Added info about external cacerts files & formatting)
 
(2 intermediate revisions by 2 users not shown)
Line 1: Line 1:
MirrorSync server runs in Java, and it needs to be able to communicate with the FileMaker Web Publishing Engine. If you have an SSL certificate installed on your web server that is self-signed or issued by an authority not recognized by Java, you need to follow these steps in order to tell Java to trust your SSL certificate.
+
MirrorSync server runs in Java, and it needs to be able to communicate with the FileMaker Web Publishing Engine. If you have an SSL certificate installed on your web server that is self-signed or issued by an authority not recognized by Java, you need to follow these steps in order to tell Java to trust your SSL certificate. Follow the procedure outlined below on the machine that will be configuring MirrorSync.
  
Step 1: Export the certificate from your web server. Use Firefox to go to the https:// address of your server. From the menu bar, go to Tools->Page Info->Security->View Certificate->Details->Export. Leave the format set to 'X.509 Certificate (PEM)' and save the certificate file somewhere on your hard drive.
+
==TrustStore Instructions==
 +
===Step 1===
 +
Export the certificate from your web server. Use Firefox to go to the https:// address of your server. From the menu bar, go to Tools->Page Info->Security->View Certificate->Details->Export. Leave the format set to 'X.509 Certificate (PEM)' and save the certificate file somewhere on your hard drive.
  
Step 2: Import the certificate into your Java key store. For OS X, go into Terminal and then cd into your Java lib/security directory, like this:
+
===Step 2===
 +
Import the certificate into your Java key store.  
  
cd /Library/Java/Home/lib/security/
+
For OS X, go into Terminal and then cd into your Java lib/security directory, like this:
  
Now run the following command to add the certificate to your keystore (replace /path/to/theCertificate.com with the path to the certificate that you exported in step 1, and replace myServerName with some descriptive name of your server):
+
<pre>cd /Library/Java/Home/lib/security/</pre>
  
sudo keytool -importcert -file /path/to/theCertficate.com -trustcacerts -alias myServerName -keystore cacerts
+
On Windows, Java may be installed in your Program Files. Using the Command window running as administrator, use the <code>dir</code> command to navigate to the Java lib/security directory.
 +
 
 +
In both Windows and Mac, run the following command to add the certificate to your keystore. Add sudo to the beginning of the command for Mac users.
 +
 
 +
<pre>keytool -importcert -file /path/to/theCertficate.com -trustcacerts -alias myServerName -keystore cacerts</pre>
 +
 
 +
Replace /path/to/theCertificate.com with the path to the certificate that you exported in step 1, and replace myServerName with some descriptive name of your server. This can be anything; it's just a reference for if you need to edit/delete it later.
  
 
You may be prompted for a keystore password - if you've never changed it, it will be 'changeit' or 'changeme'.
 
You may be prompted for a keystore password - if you've never changed it, it will be 'changeit' or 'changeme'.
Line 15: Line 24:
 
You'll be asked whether to trust the certificate - just put in 'yes' without quotes.
 
You'll be asked whether to trust the certificate - just put in 'yes' without quotes.
  
After completing this step, stop and start the Web Publishing Engine and then test it.
+
===Step 3===
 +
Stop and start the Web Publishing Engine. Return to MirrorSync and carry on with configuration.
 +
 
 +
==Notes==
 +
 
 +
Updates to Java may overwrite changes to the cacerts file. Going through this process again should solve that, but for a more permanent solution, it's possible to have MirrorSync reference a custom external cacerts file
 +
 
 +
===Instructions for using external cacerts file===
 +
First, follow the above instructions to place your certificate into the truststore, then copy the cacerts file to an external location of your choosing.
 +
 
 +
Then locate the setenv file for your instance of MirrorSync. This file is at /Library/360Works/Applications/bin/setenv.sh on OS X and C:\Program Files\360Works\Applications\bin\setenv.bat on Windows. Add the "-Djavax.net.ssl.trustStore=/your/custom/cacerts/filepath/here" option to the end of the CATALINA_OPTS string, with your external cacerts filepath substituted in. Open the 360Works Admin.jar and restart the Tomcat Application server to load these settings.

Latest revision as of 17:57, 9 February 2015

MirrorSync server runs in Java, and it needs to be able to communicate with the FileMaker Web Publishing Engine. If you have an SSL certificate installed on your web server that is self-signed or issued by an authority not recognized by Java, you need to follow these steps in order to tell Java to trust your SSL certificate. Follow the procedure outlined below on the machine that will be configuring MirrorSync.

Contents

[edit] TrustStore Instructions

[edit] Step 1

Export the certificate from your web server. Use Firefox to go to the https:// address of your server. From the menu bar, go to Tools->Page Info->Security->View Certificate->Details->Export. Leave the format set to 'X.509 Certificate (PEM)' and save the certificate file somewhere on your hard drive.

[edit] Step 2

Import the certificate into your Java key store.

For OS X, go into Terminal and then cd into your Java lib/security directory, like this:

cd /Library/Java/Home/lib/security/

On Windows, Java may be installed in your Program Files. Using the Command window running as administrator, use the dir command to navigate to the Java lib/security directory.

In both Windows and Mac, run the following command to add the certificate to your keystore. Add sudo to the beginning of the command for Mac users.

keytool -importcert -file /path/to/theCertficate.com -trustcacerts -alias myServerName -keystore cacerts

Replace /path/to/theCertificate.com with the path to the certificate that you exported in step 1, and replace myServerName with some descriptive name of your server. This can be anything; it's just a reference for if you need to edit/delete it later.

You may be prompted for a keystore password - if you've never changed it, it will be 'changeit' or 'changeme'.

You'll be asked whether to trust the certificate - just put in 'yes' without quotes.

[edit] Step 3

Stop and start the Web Publishing Engine. Return to MirrorSync and carry on with configuration.

[edit] Notes

Updates to Java may overwrite changes to the cacerts file. Going through this process again should solve that, but for a more permanent solution, it's possible to have MirrorSync reference a custom external cacerts file

[edit] Instructions for using external cacerts file

First, follow the above instructions to place your certificate into the truststore, then copy the cacerts file to an external location of your choosing.

Then locate the setenv file for your instance of MirrorSync. This file is at /Library/360Works/Applications/bin/setenv.sh on OS X and C:\Program Files\360Works\Applications\bin\setenv.bat on Windows. Add the "-Djavax.net.ssl.trustStore=/your/custom/cacerts/filepath/here" option to the end of the CATALINA_OPTS string, with your external cacerts filepath substituted in. Open the 360Works Admin.jar and restart the Tomcat Application server to load these settings.

Personal tools
Namespaces

Variants
Actions
Plug-in Products
Other Products
Navigation
Toolbox