28.1 Create the Rule Set

The rule set is an XML file that must be named ruleset.xml. Use any text editor to create this file.

28.2 Package and Install the Rule Set

The rule set defined in the ruleset.xml file must be packaged in a signed JAR file named DeploymentRuleSet.jar. The JAR file must be signed with a valid certificate from a trusted certificate authority. For information about creating and signing a JAR file, see the lesson Packaging Programs in JAR Files in the Java Tutorials.

Install the DeploymentRuleSet.jar file on your users' systems in the following directories:

• On Windows platforms, install the file in the <Windows-directory>\Sun\Java\Deployment directory, for example, c:\Windows\Sun\Java\Deployment.

• On Solaris and Linux platforms, install the file in the /etc/.java/deployment directory.

• On OS X platforms, install the file in the /Library/Application Support/Oracle/Java/Deployment/ directory.

To view the active rule set, go to the Security tab of the Java Control Panel. See the Section 20.4, "Security" for information on this tab.

28.3 Security Considerations

The Deployment Rule Set feature enables RIAs to run without notifying users of potential security risks. Review the following security considerations to be aware of the risks of using a rule set, and follow any recommendations provided:

• The location attribute of the id element is compared to the following information:

  • Location of the HTML file, for applets that do not use JNLP

  • Value of the href attribute in the JNLP file, for Java Web Start applications and applets that do use JNLP

  • Value of the jnlp_href parameter for the applet tag, for applets that use JNLP and do not provide the href attribute in the JNLP file

  If matched, then all of the content in the HTML file or JNLP file is considered trusted. However, if the web site that hosts the file is vulnerable to cross-site scripting attacks, malicious content could be injected into the HTML file or JNLP file.

• For applets that use JNLP, the location of the HTML file is not checked, so the applet could potentially be started from anywhere.

• If the location attribute is not used to match a rule to a RIA, then the HTML file or JNLP file that is used to start the RIA could be compromised. Use of the location attribute is recommended.

• Only include a path in the location attribute for a rule with an action of run if you trust the entire server. Using a path in a run rule when other locations on the server might not be trusted could present a security risk and is not recommended.

• When a path is included in the location attribute, avoid using complex paths or multi-byte characters, if possible. The path is case sensitive and UTF-8 encoding is assumed. Security exceptions occur when any unsupported characters, decoding errors, or overlong encoding is encountered. If the web server, file system, or browser normalizes the path differently, a rule based on the location attribute could return unexpected results.

• A blocking rule for a specific URI is not intended to be a robust security enforcement mechanism. For example, a rule established with a domain name can be bypassed if a user uses the IP address instead. The recommended practice is to have a final rule in your rule set with no identifiers and an action of block. Define the rules that you need to run RIAs without security prompts or with default processing, and let all other RIAs be matched by the final rule, which blocks them from running.

• Use of the HTTPS protocol is recommended for all locations.

• The order of the rules in the deployment rule set is critical. Rules are processed sequentially from the beginning of the file. When a match is found, no further rules are processed. Review your final rule set and look at both positive and negative cases to ensure that the rules cover the RIAs that you plan to manage without allowing matches to unknown RIAs.

• Rules are required for all artifacts of the RIA, such as multiple JAR files and JNLP extensions. Be careful when defining a rule for an artifact so that you do not inadvertently allow other RIAs that match the rule to run.

• Deployment rules allow RIAs to run with old versions of the JRE when needed for compatibility, however, older versions might have known security issues. Use the latest JRE whenever possible, and set the version attribute to SECURE or SECURE-version. If an older version of the JRE must be used, make any rule that requests the old version as restrictive as possible to limit the RIAs that match the rule and run with the old version. Use of all of the identifiers-location, title, and certificate hash-is recommended in this case.

• If a rule with an action of run exists for the RIA, the RIA is run even if the certificate used to sign the RIA is expired.

28.4 Examples

Example 28-1 allows all RIAs from //host.example.com/ to run without security prompts. RIAs from other locations do not match the rule so default processing is used and security prompts are shown as applicable.

<ruleset version="1.0+">
  <rule>
    <id location="//host.example.com" />
    <action permission="run" />
  </rule>
</ruleset>

To ensure that all RIAs are handled by the rule set, you can provide a final rule that matches any RIA that was not matched by a previous rule. The action for this rule must be either block or default. Example 28-2 allows all RIAs from //host.example.com:8080 to run without security prompts and blocks all other RIAs. The default message is shown when a RIA is blocked because no custom message is provided.

<ruleset version="1.0+">
  <rule>
    <id location="//host.example.com:8080" />
    <action permission="run" />
  </rule>

  <rule>
    <id />
    <action permission="block" />
  </rule>
</ruleset>

Rules are processed in the order in which they appear in the rule set. Complex patterns can be defined for matching rules by placing the rules in the correct order. Example 28-3 allows RIAs from //host.example.com to run without security prompts using a secure version of the Java 1.7 platform, but uses default processing for RIAs from //host.example.com/games, which shows applicable security prompts. RIAs from other locations do not match either rule, so default processing is used.

<ruleset version="1.0+">
  <rule>
    <id location="//host.example.com/games" />
    <action permission="default" />
  </rule>

  <rule>
    <id location="//host.example.com" />
    <action permission="run" version="SECURE-1.7" />
  </rule>
</ruleset>

Example 28-4 modifies the previous rule set and requires only the RIA named Solitaire from //host.example.com/games to run with default processing. Other RIAs from //host.example.com are allowed to run without security prompts using a secure version of the Java 1.7 platform. All other RIAs are blocked, and a custom message is shown.

<ruleset version="1.0+">
  <rule>
    <id title="Solitaire" location="//host.example.com/games" />
    <action permission="default" />
  </rule>

  <rule>
    <id location="//host.example.com" />
    <action permission="run" version="SECURE-1.7" />
  </rule>

  <rule>
    <id /> 
    <action permission="block">
      <message>Blocked by corporate. Contact J. Smith, smith@host.example.com, if you need to run this app.</message>
    </action>
  </rule>
</ruleset>

To allow multiple RIAs from multiple locations to run, and all RIAs are signed with the same certificate, you can use the certificate element to identify the RIAs with one rule instead of creating rules for each location and title. Example 28-5 allows all RIAs that are signed with the certificate used by Oracle to run without security prompts using a secure version of the Java platform. RIAs from any host ending with example.com are allowed to run with default processing. All other RIAs are blocked, and a custom message is shown.

<ruleset version="1.0+">
  <rule> <!-- allow anything signed with company's public cert --> 
    <id>
      <certificate hash="794F53C746E2AA77D84B843BE942CAB4309F258FD946D62A6C4CCEAB8E1DB2C6" />
    </id>
    <action permission="run" version="SECURE" />
  </rule>

  <rule>
    <id location="*.example.com" />
    <action permission="default" />
  </rule>

  <rule>
    <id />
    <action permission="block">
      <message>Blocked by corporate. Contact J. Smith, smith@host.example.com, if you need to run this app.</message>
    </action>
  </rule>
</ruleset> 

To force the use of a specific JRE, use the force attribute of the action element. This attribute is introduced in the 1.1 version of the Deployment Rule Set. Example 28-6 allows RIAs from //host.example.com/apps to run without security prompts using version 1.8_20 of the JRE. Any version requested by the RIA is ignored. If version 1.8_20 is not available, the RIA is blocked. All other RIAs are blocked, and a custom message is shown.

<ruleset version="1.1+">
  <rule>
    <id location="//host.example.com/apps" />
    <action permission="run" version="1.8_20" force="true" />
  </rule>

  <rule>
    <id />
    <action permission="block">
      <message>Blocked by corporate. Contact J. Smith, smith@host.example.com, if you need to run this app.</message>
    </action>
  </rule>
</ruleset> 

28.5 Java Deployment Rule Set DTD

The following example shows the DTD for the version 1.1 of the Deployment Rule Set. Version 1.1 is supported by JRE 8u20 and higher. Version 1.0 is supported by JRE 7u40 and higher. Items introduced after version 1.0 are noted.

<!ELEMENT ruleset (rule*)>
<!ATTLIST ruleset version CDATA #REQUIRED>
 
<!ELEMENT rule (id, action)>
 
<!ELEMENT id (certificate?)>
<!ATTLIST id title CDATA #IMPLIED>
<!ATTLIST id location CDATA #IMPLIED>
 
<!ELEMENT certificate EMPTY>
<!ATTLIST certificate algorithm CDATA #IMPLIED>
<!ATTLIST certificate hash CDATA #REQUIRED>
 
<!ELEMENT action (message?)>
<!ATTLIST action permission (run | block | default) #REQUIRED>
<!ATTLIST action version CDATA #IMPLIED>
<!ATTLIST action force (true|false) "false">       <!-- introduced in 1.1 -->
 
<!ELEMENT message (#PCDATA)>
<!ATTLIST message locale CDATA #IMPLIED>