RealObjects Nimbudocs Editor 3.0.3929_Beta1

Guide: Jetty & SSL


Introduction

Nimbudocs Editor supports HTTPS connections over SSL. The following types of connections are supported:

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 remove it.

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>