# Granting permissions to Derby

This section discusses which permissions should be granted to Derby (the code base `derby.jar`).

See Default Policy Implementation and Policy File Syntax at http://java.sun.com/j2se/1.4.2/docs/guide/security/PolicyFiles.html for more information about creating policy files.

#### 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 java.util.PropertyPermission "derby.*", "read"
  Allows Derby to read individual Derby properties set in the JVM machine's system set. If the action is denied, properties in the JVM machine's system set are ignored.
permission java.util.PropertyPermission "derby.storage.jvmInstanceId", "write"
  This property is used by Derby to prevent the accidental boot of the database by two class loaders. If the database is booted by two class loaders, database corruption can occur. If write permission for this property is not granted, a message is printed to the log file which indicates that the Derby database is not protected from dual boot and possible corruption.

#### Database access permissions

permission java.io.FilePermission "directory${/}/-", "read,write,delete"
  Allows Derby to manage files within the database that maps to the directory specified. For read-only databases, only the "read" action needs to be granted.

#### Optional permissions

permission java.io.FilePermission "${derby.system.home}", "read,write"
  Allows Derby to determine the system directory when set by derby.system.home and create it if needed. If the system directory already exists then only the "read" permission needs to be granted.
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 or 64 bit.
permission java.util.PropertyPermission "os.arch", "read"
  Used by Derby to determine if the system is 32 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 or 64 bit, and if the value isn't recognized a heuristic will be used instead.
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 re-directed. (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 DBA can reload the policy file by calling the `SYSCS_UTIL.SYSCS_RELOAD_SECURITY_POLICY` system procedure. For more information, see the section which describes this procedure in the Derby Reference Manual.
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 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, visit the wiki page http://wiki.apache.org/db-derby/DerbyJMX.
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 Derby's MBeans, refer to the public API (Javadoc) documentation of the package `org.apache.derby.mbeans` and its subpackages. It is possible to fine-tune this permission, for example in order 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.

#### Combining permissions

You might grant one FilePermission that encompasses several or all of the permissions instead of separately granting a number of the more specific permissions. For example:

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

This allows the Derby engine complete access to the system directory and any databases contained in the system directory.
Parent topic: Running Derby under a security manager
Related concepts
Examples of Java 2 security policy files for embedded Derby