# 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.

These permissions are also needed to run the Network Server, but the Network Server requires additional permissions as well.

These permissions are listed approximately in the order shown in Sample customized Java security policy file. Some of the optional permissions are not included in Sample customized Java security policy file.

## Mandatory permissions

permission java.lang.RuntimePermission "createClassLoader"
  Mandatory. It allows Derby to execute SQL queries and supports loading class files from jar files stored in the database.
permission org.apache.derby.security.SystemPermission "engine", "usederbyinternals"
  Mandatory. It allows Derby to access sensitive structures which application code should not touch.
permission java.util.PropertyPermission "derby.*", "read"
  Allows Derby to read individual Derby properties set in the JVM system properties. If the action is denied, the properties set in the JVM system properties are ignored.

## Optional permissions

permission java.util.PropertyPermission "user.dir", "read"
  Permits access to the system directory value if `derby.system.home` is not set or no permission has been granted to read the `derby.system.home` property.
permission java.util.PropertyPermission "sun.arch.data.model", "read"
  If set by the JVM, this is the definite answer to whether the system is 32-bit or 64-bit.
permission java.util.PropertyPermission "os.arch", "read"
  Used by Derby to determine if the system is 32-bit or 64-bit, if the system property `sun.arch.data.model` isn't set by the JVM. Derby has to recognize the value of `os.arch` to determine if the system is 32-bit or 64-bit, and if the value isn't recognized, a heuristic will be used instead.
permission java.io.FilePermission "${derby.system.home}", "read,write"
  Allows Derby to determine the system directory when it is set by `derby.system.home` and create it if needed. If the system directory already exists, only the "read" permission needs to be granted.
permission java.io.FilePermission "${derby.system.home}${/}derby.properties", "read"
  Allows Derby to read the system properties file from the system directory.
permission java.io.FilePermission "${derby.system.home}${/}derby.log", "read,write,delete"
permission java.io.FilePermission "${user.dir}${/}derby.log", "read,write,delete";
  Only one of these permissions is needed. Permits the application to read, write, and delete to the Derby log file, unless the log has been redirected. (See the `derby.stream.error` properties in the Derby Reference Manual for more information.) If one of the requested valid actions is denied, the Derby log will be `java.lang.System.err`.
permission java.security.SecurityPermission "getPolicy"
  You need this permission if you want to change the security policy on the fly and reload it into a running system. Given this permission, a System Administrator can reload the policy file by calling the `SYSCS_UTIL.SYSCS_RELOAD_SECURITY_POLICY` system procedure, which is described in the Derby Reference Manual.
permission javax.management.MBeanServerPermission "createMBeanServer";
  Allows Derby to create an MBean server. If the JVM running Derby supports the platform MBean server, Derby will automatically try to create such a server if it does not already exist. For details, see "Using Java Management Extensions (JMX) technology" in the Derby Server and Administration Guide.
permission javax.management.MBeanPermission "org.apache.derby.*#[org.apache.derby:*]", "registerMBean,unregisterMBean";
  Allows Derby to register and unregister its (JMX) MBeans. Such MBeans are associated with the domain `org.apache.derby`, which is also the prefix of the fully qualified class name of all Derby MBeans. For more information about the Derby MBeans, refer to the public API documentation of the package `org.apache.derby.mbeans` and its subpackages. It is possible to fine-tune this permission (for example, to allow access only to certain MBeans). To fine-tune this permission, see the API documentation for `javax.management.MBeanPermission` or the JMX Instrumentation and Agent Specification.
permission javax.management.MBeanTrustPermission "register";
  Trusts Derby code to be the source of MBeans and to register these in the MBean server.
permission java.lang.RuntimePermission "getProtectionDomain";
  This permission is needed if you want classpath information to be printed to `derby.log`.
permission java.sql.SQLPermission "callAbort";
  Allows Derby code to call the `java.sql.Connection.abort` method. This permission must be granted both to the Derby JDBC driver (by granting it to `derby.jar` and `derbyclient.jar`) and to the application code that calls `Connection.abort()`. Do not grant this permission to application code unless you are certain that only superusers can invoke the code.
permission java.lang.RuntimePermission "accessUserInformation";
permission java.lang.RuntimePermission "getFileStoreAttributes";
  These two permissions are needed when you are running with JDK 7 or higher and when the secure file mask settings are active (that is, when `derby.storage.useDefaultFilePermissions` is set to false, or when the server has been started from the command line (in which case secure file mask settings are active by default). See Restricting file permissions for details.
permission java.net.SocketPermission "localhost:389", "connect,resolve";
  Allows Derby code to contact the LDAP server to perform authentication. This permission must be granted to `derby.jar`. Port 389 is the default LDAP port.
permission java.lang.RuntimePermission "setContextClassLoader"
  Allows Derby to set the context class loader for long running threads to null to avoid potential for class loader leaks in application server environments when the application server starts Derby in a custom class loader.
permission java.lang.RuntimePermission "getClassLoader"
  This permission is also needed when setting the context class loader to avoid class loader leaks. The class loader for the parent is saved and set to null before creation of the thread and restored afterwards.
permission java.lang.RuntimePermission "getStackTrace";
permission java.lang.RuntimePermission "modifyThreadGroup";
  These two permissions are needed to allow extended diagnostics, specifically the stack traces of all threads, to be dumped to `derby.log` on severe errors and when the `derby.stream.error.extendedDiagSeverityLevel` property is set. See the documentation of this property in the Derby Reference Manual for details.
permission java.sql.SQLPermission "deregisterDriver";
  Allows Derby to deregister the driver. This permission is needed for system shutdown only on the Java SE 8 platform and higher, if system shutdown is invoked without the `deregister=false` connection URL attribute (see the Derby Reference Manual for details).

## Combining permissions

The Sample customized Java security policy file combines several `derby.system.home` permissions into one permission as follows:

    permission java.io.FilePermission "${derby.system.home}/-", "read,write,delete";

This permission allows the Derby engine complete access to the system directory and any databases contained in the system directory. You will probably want to restrict these liberal permissions, which allow the server to backup/restore and export/import to or from any location in the local file system.
Parent topic: Configuring Java security
Related concepts
Using a Java security policy file
Related tasks
Running the Network Server with a security manager
Running the Network Server without a security manager
Related reference
Basic security policy template
Sample customized Java security policy file