Secure access with HTTPS

eXist-db can be accessed via the network via (insecure) HTTP and (secure) HTTPS(see here for SSL configuration ). In release 1.4 HTTPS can simply be enabled by changing a configuration file, while in 1.5/trunk HTTPS is out of the box available via port 8443 (the default HTTP port is 8080).Till until recently the HTTPS port could only easily be used with a webbrowser; starting today (1.5 rev15412 and beyond) it is also usable by the eXist-db Java client and the XMLDB + XMLRPC interfaces.

Java Client

Connecting via HTTPS using the Java client is easy; start the client (using the or client.bat scripts, or via the WebStart button), the following window appears:


Select Type="Remote", click the SSL checkbox and verify the URL: it might change from 8080 (HTTP) to 8443 (HTTPS). The URL must start with . Enter your username and password, and click OK. Now the client connects to the server :


In the statusbar of the window the connection URL is visible. In this example the client is connected to the HTTPS port 8443.


For XMLDB only two steps must be made:

  1. Change the URL to contain the HTTPS port (here: 8443)
  2. Set the database property "ssl-enable" to true

A working example:

import javax.xml.transform.OutputKeys; import; import org.exist.xmldb.EXistResource; import org.xmldb.api.DatabaseManager; import org.xmldb.api.base.Collection; import org.xmldb.api.base.Database; import org.xmldb.api.modules.XMLResource; String collection = "xmldb:exist://localhost:8443/exist/xmlrpc/db"; String document = "document.xml"; // Initialize database driver Class<?> cl = Class.forName("org.exist.xmldb.DatabaseImpl"); Database database = (Database) cl.newInstance(); // Switch-on SSL for the driver database.setProperty("ssl-enable", "true"); // Register database DatabaseManager.registerDatabase(database); // Get reference to the collection Collection col = DatabaseManager.getCollection(collection); col.setProperty(OutputKeys.INDENT, "yes"); col.setProperty(EXistOutputKeys.EXPAND_XINCLUDES, "no"); col.setProperty(EXistOutputKeys.PROCESS_XSL_PI, "yes"); XMLResource res = (XMLResource) col.getResource(document); if (res == null) { System.out.println("document not found!"); } else { System.out.println(res.getContent()); }


Connecting with XMLRPC has always been possible, but a trick is required to make Java accept self-signed SSL certificates. The XMLRPC project wrote an article how to do this.

As a concenience the class org.exist.util.SSLHelper has been created to do this trick for you. The following example shows how to retrieve a document:

import java.util.Vector; import java.util.HashMap; import; import org.apache.xmlrpc.client.XmlRpcClient; import org.apache.xmlrpc.client.XmlRpcClientConfigImpl; import org.exist.util.SSLHelper; String uri = "https://localhost:8443/exist/xmlrpc"; String documentPath = "/db/document.xml"; // Initialize HTTPS connection to accept selfsigned certificates // and the Hostname is not validated SSLHelper.initialize(); // Setup XMLRPC XmlRpcClient client = new XmlRpcClient(); XmlRpcClientConfigImpl config = new XmlRpcClientConfigImpl(); config.setServerURL(new URL(uri)); config.setBasicUserName("guest"); config.setBasicPassword("guest"); client.setConfig(config); // Setup options HashMap<String, String> options = new HashMap<String, String>(); options.put("indent", "yes"); options.put("encoding", "UTF-8"); options.put("expand-xincludes", "yes"); options.put("process-xsl-pi", "no"); // Setup request parameters Vector<Object> params = new Vector<Object>(); params.addElement( documentPath ); params.addElement( options ); // Execute String xml = (String) client.execute( "getDocumentAsString", params ); System.out.println( xml );

Client command line

When the client is started as -s it reads the file Uncomment the following lines to enable the SSL secured connection :

## Secure XMLRPC (HTTPS) #uri=xmldb:exist://localhost:8443/exist/xmlrpc #ssl-enable=true

Java stack traces

Connecting to a HTTPS server is complicated, errors can appear. A typical message is show below. The message means that a client tries to connect with SSL to the server, but the server (on a specific URL) is not SSL enabled.

  • org.xmldb.api.base.XMLDBException: Failed to read server's response: Unrecognized SSL message, plaintext connection?
  • org.apache.xmlrpc.XmlRpcException: Failed to read server's response: Unrecognized SSL message, plaintext connection?
  • Unrecognized SSL message, plaintext connection