Configuring Java security

The Java security manager lets you reduce the damage that your application can do.

Using a security manager, the System Administrator can restrict how an application cooperates with other applications running in the same virtual machine (VM) or elsewhere on the same machine. When you run Derby under a security manager, you can restrict the following:

• Backups: You control where the Derby engine writes and reads database backup files.
• Imports and exports: You control where the engine imports data from and where it exports data to.
• Jar files: You control where the engine obtains jar files of customer-coded functions, procedures, types, and aggregates.
• Sockets: You control what machines can connect to the server and what machines the server can connect to.

To take advantage of these powerful controls, first customize one of the template security policies documented here. You can find these template security policies in the Derby distribution in the demo/templates directory. Choose the policy which corresponds to the Derby configuration which you are running:

• Customize Basic engine security policy template if you are embedding the Derby engine in your application, that is, if you are running the smallest footprint, core Derby configuration.
• Customize Basic server security policy template if you are running the Derby network server.
• Customize Basic client security policy template if your application runs on a remote machine and accesses Derby databases across a network.
• Customize Basic tools security policy template if you need to run Derby tools locally on the same machine as your databases.

To customize these files, make the following edits:

• URLs: Replace the ${derby.install.url} variables with a URL pointing to the directory that holds the Derby jar files. For example:

  file:///Users/me/javadb/lib/

  Alternatively, you can set the ${derby.install.url} system property (via a -D flag) when you boot the JVM.
• System home: Look for instances of the string ${derby.system.home}. Replace them with the name of the directory that holds your derby.properties file. Again, you can also set this system property when you boot the JVM.
• Tracing: Grant Derby the power to manage a directory tree that will hold server trace information. Look for the ${derby.drda.traceDirectory} variable and replace it with the directory where the server should write its diagnostic traces. For more information on Derby tracing, see "Controlling tracing by using the trace facility" in the Derby Server and Administration Guide. Again, you can also set this system property when you boot the JVM.
• Backups/imports/jars: Look for the commented-out permissions related to backup/restore, import/export, and jar file loading. If needed, uncomment these permissions, replacing the directory references with secure locations in your local file system, preferably locations which are owned by the database owner or the user who booted the JVM.
• Sysinfo: When customizing the template tools policy, you should replace <<ALL FILES>> with the directories which hold the jar files which appear on your modulepath or classpath.
• Sockets: The template policy file accepts connection requests from all hosts. You may want to restrict the template file's java.net.SocketPermission to connections from a particular subdomain. For details, see the API documentation for java.net.SocketPermission. In addition, if you are using LDAP authentication, then you must grant derby.jar the privilege to connect to the LDAP server.

This manual does not describe the Java security manager in depth. For more information, see http://docs.oracle.com/javase/8/docs/technotes/guides/security/. In particular, you may want to read the Security Architecture paper (http://docs.oracle.com/javase/8/docs/technotes/guides/security/spec/security-spec.doc.html) and the Default Policy Implementation and Policy File Syntax information (http://docs.oracle.com/javase/8/docs/technotes/guides/security/PolicyFiles.html).

• Basic engine security policy template
  Customize this policy if your application embeds the Derby engine, running Derby and application code in a single JVM process.
• Basic server security policy template
  Customize this policy if you run a Derby server, either standalone or embedded inside your application.
• Basic client security policy template
  Customize this policy if you run a client-side application, which connects to a Derby server across a network.
• Basic tools security policy template
  Customize this policy if you run Derby tools against an embedded Derby engine.
• Sample customized Java security policy file
  Here is a sample customized Java security policy file.
• Using a Java security policy file
  You can bring up the Network Server with a security manager and a customized policy file.
• Running the Network Server with a security manager
  If you start the Network Server without specifying a security manager, the Network Server installs a default Java security manager that enforces a Basic policy.
• Running the Network Server without a security manager
  You may override the Network Server's default installation of a security manager if, for some reason, you need to run your application outside of the Java security protections.