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:

The default, no SSL/TLS encryption
SSL/TLS encryption, no peer authentication
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 ( and, respectively). You can find keytool documentation for Unix and for Windows at and, 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.

Related concepts
Basic security configuration tasks
Configuring database encryption
Using signed jar files
Understanding identity in Derby
Configuring user authentication
Configuring user authorization
Configuring Java security
Restricting file permissions
Putting it all together