org.apache.river.tool

Class DebugDynamicPolicyProvider

java.lang.Object

java.security.Policy

org.apache.river.api.security.AbstractPolicy

net.jini.security.policy.DynamicPolicyProvider

org.apache.river.tool.DebugDynamicPolicyProvider

All Implemented Interfaces:

DynamicPolicy, RevocablePolicy, ScalableNestedPolicy

public class DebugDynamicPolicyProvider
extends DynamicPolicyProvider

Defines a DynamicPolicy that logs information about missing permissions, and optionally grants all permissions, which is FOR DEBUGGING ONLY. Do not use this security policy provider to grant all permissions in a production environment.

This class is intended to simplify the process of deciding what security permissions to grant to run an application. While it is generally acceptable to grant all permissions to local, trusted code, downloaded code should typically be granted the least permission possible.

The usual approach to choosing which permissions to grant is to start by running the application with a security policy file that grants all permissions to local, trusted code. When the application fails with an exception message that identifies a missing permission, add that permission to the security policy file, and repeat the process. Although straight forward, this process can be time consuming if the application requires many permission grants.

Another approach is to set the value of the "java.security.debug" system property to "access,failure", which produces debugging output that describes permission grants and failures. Unfortunately, this approach produces voluminous output, making it difficult to determine which permission grants are needed.

This security policy provider permits another, hopefully more convenient, approach. When this class is specified as the security policy provider, and granting all permissions is enabled, it uses the standard dynamic security policy to determine what permissions are granted. If a permission is not granted by the standard policy, though, then rather than denying permission, this class logs the missing permission in the form required by the security policy file, and grants the permission, allowing the program to continue. In this way, developers can determine the complete set of security permissions required by the application.

Note that the information printed by this security policy provider may not be in the form you wish to use in your policy file. In particular, using system property substitutions and KeyStore aliases may produce a more portable file than one containing the exact entries logged. Note, too, that the information printed for signedBy fields specifies the principal name for X.509 certificates, rather than the KeyStore alias, which is not a valid security policy file format.

Using this security policy provider without granting all permissions is also useful since it prints information about security exceptions that were caught, but that might have an affect on program behavior.

This class uses uses the Logger named net.jini.security.policy to log information at the following levels:

• WARNING - Permissions that were needed but not granted by the policy file.
• FINE - Also include stack traces.
• FINER - All permissions granted, with stack traces for ones not granted by the policy file, and dynamic grants.
• FINEST - All permissions granted, with all stack traces, and dynamic grants.

To use this security policy provider, do the following:

• Copy the jsk-policy.jar file from the lib-ext subdirectory of the Apache River release installation to the extensions directory of the Java(TM) 2 SDK (or JRE) installation, and copy the jsk-debug-policy.jar file from the lib subdirectory of the Apache River release installation to the extensions directory of the Java 2 SDK (or JRE) installation.
• Specify this class as the security policy provider. Create a copy of the file jre/lib/security/security/java.security, modify the file to contain the line:

   policy.provider=org.apache.river.tool.DebugDynamicPolicyProvider
   

  and then specify this new file as the value of the java.security.properties system property.
• Specify whether all permissions should be granted by setting the org.apache.river.tool.DebugDynamicPolicyProvider.grantAll security property to true by adding the following line to the security properties file:

   org.apache.river.tool.DebugDynamicPolicyProvider.grantAll=true
   

Granting all permissions is disabled by default.

Make sure to specify a security manager, either by setting the java.security.manager system property, or putting the following code in the main method of the application:

 if (System.getSecurityManager() == null) {
     System.setSecurityManager(new SecurityManager());
 }
 

This provider can be used in conjunction with the provider org.apache.river.start.AggregatePolicyProvider by setting the org.apache.river.start.AggregatePolicyProvider.mainPolicyClass system property to the fully qualified name of this class. If this provider is used with the AggregatePolicyProvider, then the JAR file jsk-debug-policy.jar needs to be in the application's class path, and this class needs to be granted all permissions.

Author:

Sun Microsystems, Inc.

Nested Class Summary

Nested classes/interfaces inherited from class java.security.Policy

Policy.Parameters

Field Summary

Fields inherited from class org.apache.river.api.security.AbstractPolicy

ALL_PERMISSION, comparator, umbrella

Fields inherited from class java.security.Policy

UNSUPPORTED_EMPTY_COLLECTION

Constructor Summary

Constructors

Constructor and Description
DebugDynamicPolicyProvider() Creates an instance of this class that wraps a default underlying policy, as specified by DynamicPolicyProvider().
DebugDynamicPolicyProvider(Policy basePolicy) Creates an instance of this class that wraps around the given non-null base policy object.

Method Summary

Modifier and Type	Method and Description
void	grant(Class cl, Principal[] principals, Permission[] permissions) Log calls.
boolean	implies(ProtectionDomain pd, Permission perm) Always returns true, but logs unique requests

Methods inherited from class net.jini.security.policy.DynamicPolicyProvider

getGrants, getPermissionGrants, getPermissions, getPermissions, grant, grantSupported, refresh, revokeSupported

Methods inherited from class org.apache.river.api.security.AbstractPolicy

checkCallerHasGrants, checkNullElements, convert, expandUmbrella, extractGrantFromPolicy, processGrants

Methods inherited from class java.security.Policy

getInstance, getInstance, getInstance, getParameters, getPolicy, getProvider, getType, setPolicy

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DebugDynamicPolicyProvider

public DebugDynamicPolicyProvider()
                           throws PolicyInitializationException

Creates an instance of this class that wraps a default underlying policy, as specified by DynamicPolicyProvider().

Throws:

PolicyInitializationException - if unable to construct the base policy

SecurityException - if there is a security manager and the calling context does not have adequate permissions to read the net.jini.security.policy.DynamicPolicyProvider.basePolicyClass security property, or if the calling context does not have adequate permissions to access the base policy class

DebugDynamicPolicyProvider

public DebugDynamicPolicyProvider(Policy basePolicy)

Creates an instance of this class that wraps around the given non-null base policy object.

Parameters:

basePolicy - base policy object containing information about non-dynamic grants

Throws:

NullPointerException - if basePolicy is null

Method Detail

grant

public void grant(Class cl,
                  Principal[] principals,
                  Permission[] permissions)

Log calls.

Specified by:

grant in interface DynamicPolicy

Overrides:

grant in class DynamicPolicyProvider

Parameters:

cl - class to grant permissions to the class loader of, or null if granting across all class loaders

principals - if non-null, minimum set of principals to which grants apply

permissions - if non-null, permissions to grant

implies

public boolean implies(ProtectionDomain pd,
                       Permission perm)

Always returns true, but logs unique requests

Overrides:

implies in class DynamicPolicyProvider