Nimbudocs Editor supports HTTPS connections over SSL. The following types of connections are supported:
- Connecting from a client application with no SSL connection to a Nimbudocs Editor server with SSL.
- Connecting from a client application with an SSL connection to a Nimbudocs Editor server with SSL.
You cannot connect to a Nimbudocs Editor server with no SSL connection if the client application itself uses SSL (i.e. you cannot perform an unsecure connection from within a secured environment).If you would like to activate SSL for the Jetty server delivered with Nimbudocs Editor by default, please see below.
Jetty & SSL
Creating a Self-Signed PKCS12 Keystore
You do not need to perform the steps in this section if you already have an SSL certificate for your Jetty server.
To create a self-signed certificate, execute the following commands on the command line (note: you will require openssl and keytool):
openssl genrsa -des3 -out jetty.key openssl req -new -x509 -key jetty.key -out jetty.crt keytool -keystore keystore -import -alias jetty -file jetty.crt -trustcacerts openssl req -new -key jetty.key -out jetty.csr openssl pkcs12 -inkey jetty.key -in jetty.crt -export -out jetty.pkcs12
For simplicity you can use the same password for all commands. If you are using different passwords, make sure to use the appropriate password when configuring the "sslContextFactory" for Jetty (see below).
IMPORTANT: if you are using a self-signed certificate, clients need to accept the certificate before they can make AJAX calls over SSL to your server. These calls will fail due to security restrictions if the certificate was not accepted by the client first. The easiest way to accept those certificates is to manually open the Nimbudocs Editor server SSL URL before loading the editor in your integration (for example, if your host is "https://yourhost.com:8443", first visit this URL and manually accept your self-signed certificate).
If an AJAX call fails due to an untrusted HTTPS connection, you will not be prompted to accept a certificate.
Import the PKCS12 Keystore in Jetty
keytool -importkeystore -srckeystore jetty.pkcs12 -srcstoretype PKCS12 -destkeystore keystore
Make sure to replace the "keystore" indicated by the "-destkeystore" parameter with the path to the Jetty keystore. It is located in "/ro/jetty9/etc/keystore" by default in the Nimbudocs Editor OVF version. If the Jetty keystore already exists, remove or rename it before creating the new keystore.
Enabling SSL in Jetty
You can now use the keystore you created to configure SSL in Jetty. Since you will have to enter the password for your keystore in the jetty-ssl.xml configuration file, we'd recommend first creating a hash from your password. You can do this as follows:
java -cp /ro/jetty9/lib/jetty-util-9.3.2.v20150730.jar org.eclipse.jetty.util.security.Password [password]
Now open the start.ini file (found in /ro/jetty9/start.ini by default in the Nimbudocs Editor OVF version) and edit/add/uncomment the following section:
#======================== # SSL Configuration #======================== #--module=https #--module=ssl #jetty.ssl.port=8443 #jetty.ssl.idleTimeout=30000 #jetty.ssl.acceptors=2 #jetty.ssl.acceptorQueueSize=100 #jetty.sslContext.keyStorePath=etc/keystore #jetty.sslContext.trustStorePath=etc/keystore #jetty.sslContext.keyStorePassword=OBF:[password] #jetty.sslContext.keyManagerPassword=OBF:[password] #jetty.sslContext.trustStorePassword=OBF:[password]
The [password] should be replaced by the hash you created using the
org.eclipse.jetty.util.security.Password as described above. If you
are using a MD5 hash of your password or your password in plain text instead, you should change the "OBF" prefix to "MD5" or
If you are using a self-signed certificate (as described above), you must activate the "lenient" mode by uncommenting the following from "/ro/jetty9/webapps/nimbueditor.xml":
<!-- Set to true/uncomment to use Nimbudocs Editor with a self-signed certificate, or if you experience other SSL issues. --> <!-- <Call name="setInitParameter"> <Arg>lenient</Arg> <Arg>true</Arg> </Call> -->
Now restart Jetty to apply the changes. If you are using the Nimbudocs Editor OVF, you can do so using the following command:
sudo /etc/init.d/jetty restart
Update the Integration Code
Your Jetty server is now ready to serve Nimbudocs over SSL. All you need to do know is to update your integration code to use
the new SSL connection. To so, change the URL the
nimbudocseditor.js is loaded from to the SSL port you configured (8443)
in the example above, and also update the URL passed to the "NimbudocsEditor.create" method. Example:
<script src="https://yourhost:8443/nimbudocseditor.js"></script> <script> . . . NimbudocsEditor.create("nimbuContainer", "https://yourhost:8443", options); </script>