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 and procedures.
• 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 a copy of the Derby security policy template. You will find a template security policy in the Derby distribution at demo/templates/server.policy.

Basic security policy template shows this basic policy. It grants permissions to both the derby.jar and derbynet.jar codebases. To run Derby in embedded mode, you must grant permissions to derby.jar. To run the Derby Network Server, you must grant permissions to both derby.jar and derbynet.jar.

Sample customized Java security policy file shows a sample customized policy file.

To customize the file, 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/

• 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.
• 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.
• Backups/imports/jars: Look for the first instance of the string <<ALL FILES>>. Make two more copies of this line so that there are three copies of this line in the file. On the first line, replace <<ALL FILES>> with the directory tree that you will use for holding database backups. For example:

  /Users/me/backups

  Similarly, on the second line, replace <<ALL FILES>> with the directory tree which you will use for staging imported/exported data. On the third line, replace <<ALL FILES>> with the directory tree that holds the jar files of functions and procedures that you will load into databases. For the detailed syntax of these lines, see the API documentation for java.io.FilePermission.

• Sysinfo: The sysinfo logic appears redundantly in several Derby jar files:

  derby.jar
  derbynet.jar
  derbyclient.jar
  derbytools.jar

  If you want to run the sysinfo command, you will need to grant permissions to the first of these jar files that appears in your classpath.

  Note: If you are running Derby by using the command java -jar derbyrun.jar, the first relevant jar file in the classpath is derby.jar. The template policy file grants these permissions to derbynet.jar. Note that the template policy file grants sysinfo the privilege to read all files in the system. You can restrict this to just the directory that contains the jar files wired into your 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 security policy template
  If you start the Network Server without specifying a security manager, the Network Server will install a default Java security manager that enforces a basic policy.
• 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 embedded Derby with a security manager
  This section describes the permissions that should be granted to the codebase derby.jar to allow you to run embedded Derby with a security manager.
• 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.