Skip Headers

Oracle TopLink Developer's Guide 10g Release 3 (10.1.3) B13593-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# Understanding Security Permissions

By default, when you run a TopLink-enabled application in a JVM configured with a nondefault `java.lang.SecurityManager`, the TopLink run time executes certain internal functions by executing a `PrivilegedAction` with `java.security.AccessController` method `doPrivileged`. This ensures that you do not need to grant many permissions to TopLink for it to perform its most common operations. You need only grant certain permissions depending on the types of optional TopLink features you use (see "Permissions Required by TopLink Features").

While using `doPrivileged` method provides enhanced security, it will severely impact overall performance. Alternatively, you can configure TopLink to disable the use of `doPrivileged` method even when a nondefault `SecurityManager` is present (see "Disabling doPrivileged Operation"). In this case, you must grant TopLink all required permissions (see "Permissions Required by TopLink Features" and "Permissions Required When doPrivileged is Disabled").

Note: While enabling the use of `doPriviledged` method enhances TopLink application security, it does not guarantee that secure code cannot be called by application code in ways that the system did not intend. You must consider the use of `doPriviledged` method within the context of your overall application security strategy. For more information, see `http://java.sun.com/security/index.jsp`.

If you run a TopLink-enabled application in a JVM without a nondefault `SecurityManager`, you do not need to grant any permissions.

## Permissions Required by TopLink Features

When you run a TopLink-enabled application in a JVM configured with a nondefault `java.lang.SecurityManager` and `doPrivileged` operation is enabled, you may need to grant additional permissions if your application requires any of the following:

- System Properties

- Loading project.xml or sessions.xml Files

- Cache Coordination

- Accessing a Data Source by Port

- Logging With java.util.logging

- J2EE Application Deployment

### System Properties

By default, a TopLink-enabled application requires access to the system properties granted in the default `<``JAVA_HOME``>/lib/security/java.policy` file. If your application requires access to other platform-specific, environment, or custom properties, then grant further `PropertyPermission` permissions as Example 7-6 shows.

Example 7-6 Permissions for System Properties

    permission java.util.PropertyPermission "my.property", "read";

### Loading project.xml or sessions.xml Files

Most TopLink-enabled applications read in `project.xml` and `sessions.xml` files directly. Grant permissions to the specific files or file locations as Example 7-7 shows. This example assumes that both `project.xml` and `sessions.xml` files are located in the same directory (given by application-specific system property `deployment.xml.home`). Alternatively, you can specify a separate `FilePermission` for each file.

Example 7-7 Permissions for Loading Deployment XML Files

    permission java.io.FilePermission "${deployment.xml.home}/*.xml", "read";

For information on `FilePermission` settings for J2EE applications, see "J2EE Application Deployment".

### Cache Coordination

If your application uses cache coordination (see "Understanding Cache Coordination"), then grant `accept`, `connect`, `listen`, and `resolve` permissions to the specific sockets used by your coordinated cache as Example 7-8 shows. This example assumes that the coordinated cache multicast port (see "Configuring a Multicast Port") is 1024.

Example 7-8 Permissions for Cache Coordination

    permission java.net.SocketPermission "localhost:1024-", "accept, connect, listen, resolve";

### Accessing a Data Source by Port

If your TopLink-enabled application accesses a data source using a socket, then grant `connect` and `resolve` permissions for that socket as Example 7-9 shows. This example assumes that the host name (or IP address) of the remote host that provides the data source (such as a relational database server host) is given by application-specific system property `remote.data.source.host` and that this host accepts data source connections on port 1025.

Example 7-9 Permissions for non-J2EE Data Source Connections

    permission java.net.SocketPermission "${remote.data.source.host}:1025-", "connect, resolve";

For J2EE applications, data source socket permissions are usually handled by the application server.

### Logging With java.util.logging

If you configure your TopLink-enabled application to use `java.util.logging` package (see "Configuring Logging"), then grant your application `control` permissions as Example 7-10 shows.

Example 7-10 Permissions for java.util.logging

    permission java.util.logging.LoggingPermission "control"

### J2EE Application Deployment

If you are deploying a TopLink-enabled J2EE application, you must grant permissions for:

- The `toplink.jar` file. For example:

      grant codeBase "file:<TOPLINK_HOME>/jlib/toplink.jar" {  permission java.security.AllPermission;};

If you are using an XML platform, you must also grant the following permissions:

- The `toplink.xml.platform` system property. For Example:

      permission java.util.PropertyPermission "toplink.xml.platform", "read"

## Permissions Required When doPrivileged is Disabled

If you disable `doPrivileged` operation when you run a TopLink-enabled application in a JVM configured with a nondefault `java.lang.SecurityManager`, you must grant the following permissions:

- `java.lang.reflect.RelectPermission "suppressAccessChecks"`

- `java.lang.RuntimePermission "accessDeclaredMembers"`

- `java.lang.RuntimePermission "getClassLoader"`

You may also have to grant additional permissions depending on the TopLink features your application uses. For more information, see "Permissions Required by TopLink Features".

## Disabling doPrivileged Operation

To disable `doPrivileged` operation when you run a TopLink-enabled application in a JVM configured with a nondefault `java.lang.SecurityManager`, set system property `oracle.j2ee.toplink.security.usedoprivileged` to `false`. If you are using OC4J, set system property `oracle.j2ee.security.usedoprivileged` to `false`.

To enable `doPrivileged` operation, set these system properties to `true`.