SSL Configuration

The <ssl> configuration element specifies Secure Sockets Layer (SSL) settings for secure communication in client-server mode, for both the client side and the server side.

The default configuration file contains the following <ssl> element:

<ssl enabled="false">
  <server-keystore path="$objectdb/ssl/server-kstore" password="pwd" />
  <client-truststore path="$objectdb/ssl/client-tstore" password="pwd" />
</ssl>

The enabled attribute of the ssl element (whose value is "true" or "false") specifies if SSL is used. As shown above, SSL is disabled by default. It could be enabled when accessing remote ObjectDB databases over an insecure network such as the Internet.

SSL Keystore and Truststore Files

To use SSL you have to generate at least two files:

• A Keystore file that functions as a unique signature of your server. This file contains general details (such as a company name), an RSA private key and its corresponding public key (the SSL protocol is based on the RSA algorithm).
• A Truststore file that functions as a certificate that enables the client to validate the server signature. This file is generated from the Keystore file by omitting the private key (it still contains the general information and the public key).

You can generate these files using the JDK keytool utility:

https://docs.oracle.com/javase/6/docs/technotes/tools/solaris/keytool.html

Using these Keystore and Trustore files a client can verify during SSL handshaking that it is connected to the real server and not to another server, pretending to be the real server (this is known as a "man in the middle attack"). The server, on the other hand, might be less selective and allow connections from any machine as long as a valid username and password are provided. If authenticating the client machine by the server is also required a Keystore file (which might be different from the server Keystore) has to be installed on the client machine and its corresponding Trustore file has to be installed on the server machine.

Setting the Configuration

<ssl enabled="true">
  <server-keystore path="$objectdb/ssl/server-kstore" password="pwd" />
  <server-truststore path="$objectdb/ssl/server-tstore" password="pwd" />
  <client-keystore path="$objectdb/ssl/client-kstore" password="pwd" />
  <client-truststore path="$objectdb/ssl/client-tstore" password="pwd" />
</ssl>

To use SSL the enabled attribute of the ssl element has to be set to true.

Every Keystore / Truststore file is represented by a separate child element with two required attributes: path, which specifies the path to the file, and password, which specifies a password that is needed in order to use the file.

Usually only the server-keystore element (for the server) and the client-truststore element (for the client) are needed (as shown above).

The other two elements, client-keystore and server-truststore, are needed only when the client is also signed (as explained above).

Connecting using SSL

Connecting to an SSL-enabled ObjectDB server requires specifying the "objectdbs" protocol (instead of the standard "objectdb" protocol) in the connection URL on the client side:

EntityManagerFactoryjavax.persistence.EntityManagerFactoryJPA interfaceInterface used to interact with the entity manager factory
 for the persistence unit.See JavaDoc Reference Page... emf = Persistencejavax.persistence.PersistenceJPA classBootstrap class that is used to obtain an EntityManagerFactory
 in Java SE environments.See JavaDoc Reference Page....createEntityManagerFactorycreateEntityManagerFactory(persistenceUnitName)Persistence's static methodCreate and return an EntityManagerFactory for the named
 persistence unit.See JavaDoc Reference Page...(
      "objectdbs://localhost/myDbFile.odb;user=admin;password=admin");