Release Notes for Apache Derby 10.10.2.0

Summary of Change

Additional permission needed to run Derby network server

Symptoms Seen by Applications Affected by Change

An additional java.net.SocketPermission, "listen" was added to the default network server policy file, and the policy file template. The documentation was updated to describe this permission.

Incompatibilities with Previous Release

No incompatibilities arise from upgrading a Derby release to one with the additional permissions in the policy file.
However, unless you have this permission, when upgrading to a JVM release that has JDK 7u51 incorporated, your network server may not start if

• you use network server on a port not within the ephemeral ports specified by the OS.
• and
  • you rely on the default derby policy file, or
  • you have a customized policy file without this permission

Rationale for Change

An additional permission may be needed in order to bring up the Derby network server after upgrading to JVMs incorporating JDK 7u51. In particular, the startup scripts may fail to boot the network server.

This is a result of the "Better applet networking" changes made for JVM issue 8011787 (not public): the default socket permissions assigned to all code including untrusted code have been changed.
Previously, all code was able to bind any socket type to any port number greater than or equal to 1024. It is still possible to bind sockets to the ephemeral port range on each system. The exact range of ephemeral ports varies from one operating system to another, but it is typically in the high range (such as from 49152 to 65535).
The new restriction is that binding sockets outside of the ephemeral range now requires an explicit permission in the system security policy.

After upgrading to a JVM with these changes, while attempting to boot, the network server may fail and raise the following error:

access denied ("java.net.SocketPermission" "localhost:1527" "listen,resolve") java.security.AccessControlException: access denied ("java.net.SocketPermission" "localhost:1527" "listen,resolve")

To workaround this problem, you must bring up the network server with a security policy which includes the now required missing permission. Instead of booting the network server as:

java org.apache.derby.drda.NetworkServerControl start

boot the network server as follows:

java -Djava.security.manager -Djava.security.policy=${yourPolicyFile} org.apache.derby.drda.NetworkServerControl start

where ${yourPolicyFile} is a file containing a customized version of the policy file described in the Derby Admin Guide section titled Basic Network Server security policy. You must customize that generic policy file to fit your application. In addition, you must add the following permission to the permissions block granted to the ${derby.install.url}derbynet.jar codebase:

permission java.net.SocketPermission "localhost:${port}", "listen";

where ${port} should be replaced by the port number where the network server listens for incoming connection requests. By default, that is port 1527.

For more information on Derby security policies, see the Derby Admin Guide sections titled Network Server security and Running the Network Server under the security manager.

If you are using replication, a similar permission must be granted to the security policy for the slave server. Add the following permission to the ${derby.install.url}derby.jar codebase:

permission java.net.SocketPermission "localhost:${slavePort}", "listen";

where ${slavePort} should be replaced by the port number where the slave server listens for incoming connection requests (typically 4851). For more information on the security policy for the slave server, see the Derby Admin Guide section titled Replication and security.

With this fix, the default policy file has received these required permissions, and the scripts in the bin directory work again. However, it may still be necessary to adjust any customized policy files.

Application Changes Required

Applications need not make any change to take advantage of the new permission granted in the default policy file. However, the default policy file may, or may not be sufficient for specific applications and it is better to use your own policy file. If you have your own policy file, you may need to adjust it to add the "listen" permission as appropriate.

Summary of Change

After the fix, statement level update triggers defined on specific columns will only fire for the update of any of those specified columns. Additionally, after the fix, statement level update triggers defined at the table level will fire correctly for columns added after the CREATE TRIGGER sql is issued.

Symptoms Seen by Applications Affected by Change

Statement level update triggers defined for specific columns fired on update of columns which were not included in the CREATE TRIGGER sql. Also, statement level update triggers defined at table level did not fire for newly added columns.

Incompatibilities with Previous Release

Derby releases 10.7.1.4, 10.8.1.2, 10.9.1.0, 10.10.1.1 suffer from DERBY-6383 and will see 1)update statement triggers defined at column(s) level firing for columns not specified in the column list of the "CREATE TRIGGER... AFTER UPDATE... OF" clause 2)update statement triggers defined at table level not firing for columns added to the table after CREATE TRIGGER was issued.

Rationale for Change

The fix for the regression identified in DERBY-6383 will now make update statement level triggers adhere to SQL standards.

Application Changes Required

In order to fix the buggy triggers created in the above mentioned releases, users will need to manually drop and recreate the statement level update triggers in a release with DERBY-6383 fix. All statement level update triggers, whether they are defined on specific columns or at the table level, should be dropped and recreated.

Summary of Change

Frame injection vulnerability in old versions of the API documentation.

Symptoms Seen by Applications Affected by Change

Many of the previous releases of Apache Derby were built with JDK versions whose javadoc tool produced HTML files that had a frame injection vulnerability (CVE-2013-1571). The API documentation bundled with this version of Apache Derby has been built with a version of the javadoc tool that does not suffer from the vulnerability.

Rationale for Change

The change removes a vulnerability.

Application Changes Required

API documentation for old versions of Apache Derby on public-facing web servers should be fixed by

• removing the old versions of the API documentation, or
• replacing the old versions of the API documentation with the new, fixed version in this release, or
• repairing the vulnerable versions of the API documentation using Oracle's Java API Documentation Updater Tool

Summary of Change

New SQLPermission needed for JDBC driver deregistration on Java SE 8.

Symptoms Seen by Applications Affected by Change

The symptoms are only seen when running an application under a Java security manager on Java SE 8 or later.

When running the Apache Derby embedded driver under a Java security manager on Java SE 8, the embedded driver will not be deregistered during system shutdown unless SQLPermission("deregisterDriver") has been granted to derby.jar.

If this situation has occurred, the following message will be printed to the Derby error log (derby.log) along with a stack trace that tells where the call was made:

Could not deregister the JDBC driver during engine shutdown. Make sure SQLPermission("deregisterDriver") is granted to derby.jar.

Also, if an application attempts to deregister a JDBC driver by calling java.sql.DriverManager.deregisterDriver() directly, it may fail with an AccessControlException. This is not limited to the Apache Derby embedded driver; it will happen for any JDBC driver, including the Apache Derby network client driver.

Incompatibilities with Previous Release

When running on Java SE 7 or earlier, shutting down an embedded Derby engine would also deregister the embedded driver from java.sql.DriverManager's list of JDBC drivers.

When running on Java SE 8 or later, the embedded driver will still be registered after shutdown if derby.jar is not allowed to invoke java.sql.DriverManager.deregisterDriver().

Rationale for Change

This is a change in the java.sql.DriverManager class in Java SE 8. It is not a change in Apache Derby.

Application Changes Required

Applications that run under a Java security manager, and that depend on the driver being deregistered as a side-effect of shutting down the embedded engine, need to grant java.sql.SQLPermission("deregisterDriver") to derby.jar.

Applications that run under a Java security manager, and that call java.sql.DriverManager.deregisterDriver() directly, need to grant java.sql.SQLPermission("deregisterDriver") to the application code base, and possibly also change the call to deregisterDriver() to go through java.security.AccessController.doPrivileged().

Summary of Change

When running a server started from the command line with a security manager and a customized policy file, new permissions may be have to be added to it.

Symptoms Seen by Applications Affected by Change

Running the server will fail with a AccessControlException indicating a missing permission, whereas running the server in the same way used to work before upgrading Derby.

Incompatibilities with Previous Release

Server will not run for affected configurations.

Rationale for Change

It is good security practice to limit data base file visibility to the operating system account that creates the database. In this release of Derby this policy is in effect by default when starting the network server from the command line unless this functionality has been explicitly disabled, cf. description of the property derby.storage.useDefaultFilePermissions in the Reference Manual. Cf. also Derby issue DERBY-5363.

Note: for other configurations, this policy must be explicitly enabled, e.g when starting the server via the Java API. Similarly, embedded Derby doesn't use the new policy by default. If you enable the new policy in such configurations and a security manager is used, you will need to add the permission described below to the Java security policy file.

Application Changes Required

The implementation of this security policy requires that the policy file in use by the server has a few more permissions than before. When running with the default security policy that is taken care of. However, for user customized policy files, these permissions need be added. The permissions that need be added are:

• codebase derbynet.jar:

          permission java.lang.RuntimePermission "accessUserInformation";
  	permission java.lang.RuntimePermission "getFileStoreAttributes";
  	permission java.util.PropertyPermission "derby.__serverStartedFromCmdLine", "read, write";
      

• codebase derby.jar

          permission java.lang.RuntimePermission "accessUserInformation";
  	permission java.lang.RuntimePermission "getFileStoreAttributes";
      

See also the template security policy file provided with Derby at demo/templates/server.policy and the section Customizing the Network Server's security policy in the Derby Server and Administration Guide.

Summary of Change

Datatype Change in JDBC Metadata

Symptoms Seen by Applications Affected by Change

The datatype has changed for two of the columns in the ResultSet returned by DatabaseMetadata.getIndexInfo(). Previously, the CARDINALITY and PAGES columns were INTs. Now they are BIGINTs.

Rationale for Change

JDBC 4.2 changed the datatype of these columns.

Application Changes Required

Note that on Derby, the contents of these columns is always NULL. Applications may need to be recoded if they expect the metadata for these columns to report that they have INT type rather than BIGINT type.

Summary of Change

The meaning of SYS.SYSTRIGGERS.CREATIONTIMESTAMP has changed.

Symptoms Seen by Applications Affected by Change

In earlier versions of Apache Derby, the SYS.SYSTRIGGERS.CREATIONTIMESTAMP column would tell what time the system clock showed, represented in the local time zone of the database, at the time the trigger was created.

In databases whose format is upgraded to 10.11 or later, this column now represents the time the trigger was created in the UTC time zone. Existing values are not changed in the upgrade, so the creation timestamps for any triggers created before the upgrade will still be represented in the local time zone.

Furthermore, logic has been added to make the values in that column monotonically increasing, so in some special cases (especially if the system clock has been adjusted back in time, or if the database has been moved to a machine whose system clock is behind the clock on the original machine) the column may contain a value that is not equal to the time the trigger was created. The latter change also takes effect if the database format has not been upgraded to 10.11 or later.

Rationale for Change

The purpose of the SYS.SYSTRIGGERS.CREATIONTIMESTAMP column is to make it possible to fire triggers in the order in which they were created. A timestamp in the local time zone is not ideal for this purpose because there are ambiguities in time zones that observe daylight saving time. Also, there could be ambiguities when moving a database to a machine in another time zone. Storing the timestamp in UTC avoids both of these problems.

Another problem that was seen, was that triggers that were created quickly after each other, could sometimes end up with the exact same creation timestamp. This meant that the execution order for those triggers was non-deterministic. The timestamp of a new trigger is now adjusted so that it is higher than the timestamp of any other existing trigger on the same table. This makes sure the triggers are executed in the order in which they were created.

Application Changes Required

Most applications should not be affected by this change in any way. Any applications that read the values stored in SYS.SYSTRIGGERS.CREATIONTIMESTAMP should take into account that this column doesn't necessarily tell the exact time the trigger was created, because it contains a value that may have been adjusted in order to ensure the correct execution order.