Configuring SSL/TLS

By default, network traffic travels in cleartext between Derby clients and servers.

By using a man-in-the-middle ploy, a clever attacker can read all of the string data shipped to and from the server. By knowing the Derby wire protocol, a clever attacker can read numeric data too. Even worse, the man-in-the-middle can change the data while it is traveling between the client and the server.

Fortunately, Derby can encrypt network traffic using the SSL/TLS (Secure Socket Layer/Transport Layer Security) logic supplied with the virtual machine. As a side effect, SSL/TLS raises an extra authentication hurdle too, involving peer authentication.

The term peer is used for the other part of the server-client communication: the server's peer is the client, and the client's peer is the server.

SSL/TLS for Derby (both for client and for server) operates in three possible modes:

off

The default, no SSL/TLS encryption

basic

SSL/TLS encryption, no peer authentication

peerAuthentication

SSL/TLS encryption and peer authentication

Peer authentication may be set on the server, on the client, or on both. Peer authentication means that the other side of the SSL/TLS connection is authenticated based on a trusted certificate installed locally.

Before using this encryption technology, you will want to familiarize yourself with SSL/TLS concepts such as key pairs and certificates, and with the JDK's keytool application. You can find useful overviews of SSL/TLS at Apache and Wikipedia (http://httpd.apache.org/docs/2.0/ssl/ssl_intro.html and http://en.wikipedia.org/wiki/Secure_Sockets_Layer, respectively). You can find keytool documentation for Unix and for Windows at http://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html and http://docs.oracle.com/javase/8/docs/technotes/tools/windows/keytool.html, respectively.

Network encryption requires the following setup steps:

1. Client certificates: Each client must generate a client key pair and certificate. The client certificates must be loaded into the server's trust store.
2. Server certificate: The server must generate a server key pair and certificate. All of the clients must load the server's certificate into their respective trust stores.
3. Server startup: The server must be booted with system properties and a startup option that turn on SSL/TLS encryption.
4. Client startup: The client must be started with system properties that turn on SSL/TLS encryption. In addition, an extra attribute is added to the JDBC connection URL.

To use SSL/TLS to encrypt Derby's network traffic, the client must have a key store for holding its own public/private key pair. The client must also have a trust store for holding the server's certificate. If the key store and trust store do not already exist, the keytool program will create them. Suppose that the client stores its public/private key pair in ~/vault/ClientKeyStore, and suppose that the client stores certificates from other systems in ~/vault/ClientTrustStore.

• Creating a client key pair and certificate
  Follow these steps to create a client key pair and a client certificate.
• Creating a server key pair and certificate
  Follow these steps to create a server key pair and a server certificate.
• Importing certificates
  Follow these steps to import each certificate into the other's trust store.
• Booting the server and connecting to it
  Finally, boot the server and start the client.
• Key and certificate handling
  For SSL operation, the server always needs a key pair. If the server runs in peer authentication mode (the server authenticates the clients), each client needs its own key pair. In general, if one end of the communication wants to authenticate its partner, the first end needs to install a certificate generated by the partner.
• Starting the server with SSL/TLS
  For server SSL/TLS, a server key pair needs to be generated. If the server is going to do client authentication, the client certificates need to be installed in the trust store.
• Running the client with SSL/TLS
  Basic SSL encryption on the client is enabled either by the URL attribute ssl, the property ssl, or the datasource attribute ssl set to basic.
• Other server commands
  The other server commands (shutdown, ping, sysinfo, runtimeinfo, logconnections, maxthreads, timeslice, trace, and tracedirectory) are implemented as clients, and they behave exactly as clients with regards to SSL.