Deployment Rule Set

Java Rich Internet Applications Guide > Security > Deployment Rule Set

This page includes the following topics:

Overview

The Deployment Rule Set feature is for enterprises that manage their Java desktop environment directly, and provides a way for enterprises to continue using legacy business applications in an environment of ever-tightening Java applet and Java Web Start application security policies.

Java applets and Java Web Start Applications, known collectively as Rich Internet Applications (RIAs), are accessed from a web server through a browser. To protect the user and minimize the possibility that a RIA was compromised, security checks are performed when a RIA is started, and the user is prompted for permission to run the RIA. The Deployment Rule Set feature enables an enterprise to establish a whitelist of known applications. Applications on the whitelist can be run without most security prompts, however, the following prompts are not suppressed:

Rules for deployment are defined in an XML file and packaged in a signed JAR file. The rules are tested sequentially until one matches the RIA. Depending on the action assigned to the rule, the RIA is then run without security prompts, blocked from running, or run with default processing that shows any security prompts that are applicable. If no rules are matched, then default processing is used. The rules also provide the ability to specify the version of the JRE that is used to run the RIA and suppress the notification of out-of-date JREs.

An active rule set that is installed on the system can be viewed from the Security tab of the Java Control Panel. See the Security section of Java Control Panel for more information.

The Deployment Rule Set feature requires the new Java Plug-in (available since Java SE 6 Update 10). Use of the old Java Plug-in is not supported. If a deployment rule set is installed, usage of the old plug-in is blocked for all RIAs.


Note: The Deployment Rule Set feature is optional and shall only be used internally in an organization with a controlled environment. If a JAR file that contains a rule set is distributed or made available publicly, then the certificate used to sign the rule set will be blacklisted and blocked in Java.


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.

Define the Rules

Define the rules that you need to run or block RIAs for your organization. See Java Deployment Rule Set DTD for the syntax of the rule set. Unknown elements or attributes are ignored. Valid elements are described in the following table.

Element Description Attributes

ruleset

Top-level element of the policy file. The version attribute is required.

The valid child element is rule.

  • version - Minimum version of the Deployment Rule Set specification that is required to process this file. Use a plus sign (+) to indicate that later versions can also be used, for example 1.0+. As of the 7u40 release, the Deployment Rule Set version is 1.0.

rule

Identifies a RIA or set of RIAs and the action taken. A rule element contains one id and one action element. Rules are processed sequentially until a rule is matched. When a match is found, no further rules are processed. If no rule is matched, then default processing is used, and any relevant security prompts or warnings are shown. The valid child elements are id and action.

When a RIA has artifacts that are signed with a different certificate or that are in a different location, ensure that the rule set contains rules for all artifacts of the RIA. For mixed code cases, which are calls between JAR files with different permission levels or calls from JavaScript code to privileged Java code, see Set Up Rules for Mixed Code for additional information.

The valid parent element is ruleset. The valid child elements are id and action.

None

id

Identifies the RIA or set of RIAs to which the rule applies. To be considered a match, the RIA must match all attributes and child elements present.

If no attributes or child elements are present, then the rule matches all RIAs. If the action for a rule is run, then at least one attribute or child element must be present.

The valid parent element is rule. The valid child element is certificate.

  • location - URL of the source of the RIA. For RIAs that use JNLP, this value is matched to the location of the JNLP file, or the canonical home of the RIA if there is no JNLP file. For a JNLP extension, this value is matched to the location of the extension element in the resource element of the main artifact. For RIAs that do not use JNLP, this value is matched to the URL for the HTML file. The path is case sensitive and UTF-8 encoding is assumed.

    Use of the HTTPS protocol is strongly recommended to avoid potential man-in-the middle attacks.

    A location is matched based on the following guidelines:

    • If provided, then the protocols must match exactly.
    • The host name can start with an asterisk followed by a dot (*.), which then matches any host that ends with the string provided after the dot. For example, *.example.com matches host.example.com and host.test.example.com. The host name cannot be just an asterisk.
    • If provided, then the port numbers must match exactly.
    • If provided, then the beginning of the paths must match exactly. If the location attribute does not contain a path, then all paths from the host are considered a match. For example, host.example.com/samples matches host.example.com/samples and host.example.com/samples/test, but does not match host.example.com/test. However, host.example.com matches host.example.com/samples, host.example.com/samples/test, and host.example.com/test.

    If the location attribute is not present, or the value is null, then the location matches all RIAs.

  • title - String used in the title element of the JNLP file, or as used by the Java Plug-in. If the title attribute is present and the value is not null, then the value must match the title of the RIA exactly. If the title attribute is not present, or the value is null, then the title matches all RIAs.

    If the action for a rule is run or default and the title attribute is present, another id attribute or child element must be specified with the title attribute, otherwise the rule is invalid.

certificate

Identifies the certificate used to sign the RIA. The hash attribute is required.

The valid parent element is id. The certificate element has no child elements.

  • algorithm - String that defines the hashing algorithm used to generate the value for the hash attribute. Currently, only security hash algorithm SHA-256 is supported. If the value is null, then SHA-256 is used.

  • hash - String of hexadecimal digits that represent the hash value of the code signing certificate. The value is based on the hashing algorithm specified for the algorithm attribute. See Get the Certificate Hash for information on getting the value to use.

action

Defines the action taken for any RIA that matches the rule.

The valid parent element is rule. The valid child element is message.

  • permission - Action taken. The following values are valid:

    • run - The following types of RIAs are allowed to run without prompts:

      • Signed with a valid certificate from a trusted certificate authority
      • Signed with an expired certificate
      • Self-signed
      • Unsigned
      • Missing required JAR file manifest attributes

      A RIA is blocked if it is signed with a certificate that is blacklisted or known to be revoked, even though the action is set to run.

    • block - RIA is not run. A message is shown to the user. To provide a custom message, include the message element.

    • default - RIA is run with default processing and any applicable security prompts are shown.

  • version - String that identifies the version of the JRE to use to run the RIA. This attribute applies only when the value for the permission attribute is run. Use the version attribute when an older JRE is needed for compatibility with specific RIAs. If the version attribute is not present, the RIA is run with the latest JRE available.

    The following values are valid:

    • Product version, such as 1.7.0_40, 1.7*, or 1.7.0_40+. Use an asterisk (*) after the number to request the use of any version that begins with the number before the asterisk. Use a plus sign (+) after the number to request the use of the specified version or any later version.
    • SECURE. The SECURE keyword requests the use of any secure version.
    • SECURE-version, where version is a valid platform version, such as SECURE-1.7. The SECURE-version keyword requests the use of any secure version of the specified platform, or the specified platform or later when a plus sign (+) follows the platform.

    The version of the JRE that is used is determined by the following order of precedence:

    1. The current version of the JRE is used if it is available and matches both the version attribute and the version requested by the RIA.
    2. The latest available version of the JRE is used if it matches both the version attribute and the version requested by the RIA.
    3. The current version of the JRE is used if it is available and matches the version attribute.
    4. The latest available version of the JRE is used if it matches the version attribute.

    If no version is available that meets the criteria, then the RIA is blocked, and a message is shown to the user. To provide a custom message, include the message element.

message

Message shown to the user if the RIA is blocked. Use only plain text for the message, HTML tags and other special formatting are not supported. If this element is not present, then a default message is shown.

To support multiple locales, include a message element for each locale. Define locale-specific messages after any message that does not include a locale. All messages are checked and if more than one message matches the user's locale, then the last message matched is used.

If the locale attribute is not specified, then the message is used for any locale for which a message element is not provided. If a message element for the user's locale is not provided and a message element without a locale is not present, then a default message is shown.

To ensure that the dialog box that shows the message fits the screen, keep the message under 1024 characters and test for all locales provided.

The valid parent element is action. The message element has no child elements.

  • locale - Locale to which the message applies.

See Examples for some sample rule sets.

If the rule set is invalid, then an error that describes the problem is shown and all RIAs are blocked. Either the ruleset.xml file must be corrected, or the DeploymentRuleSet.jar file must be removed from the deployment directory (see Package and Install the Rule Set for the location of this directory) before RIAs can be run. If a rule set is reported as invalid, then check for the following problems based on the error you received:

If the DeploymentRuleSet.jar file is removed, RIAs are handled by the default deployment process.

Set Up Rules for Calls From JavaScript Code (LiveConnect)

If you need to make calls to your RIA from JavaScript code, then apply the following guidelines to prevent the calls from being blocked:

If the JavaScript code is calling privileged code and you want to suppress mixed code warnings, see Set Up Rules for Mixed Code.

Set Up Rules for Mixed Code

When you create your rule set, ensure that you have rules for all of the artifacts that are associated with the RIAs. Additional rules might be needed to suppress mixed code security warnings that are generated when calls are made between code with different permission levels, or from JavaScript code to privileged Java code. To suppress the mixed code security warnings, include rules in your rule set based on the following requirements of your RIA:

Be aware that the rules shown in this section for suppressing the mixed code prompt also suppress the other security prompts for any RIA that matches the rule. Make sure that your rules are defined in the order needed to provide the control that you want.

Get the Certificate Hash

If you want to define a rule that uses the certificate hash to match RIAs, you need to obtain the correct string of hexadecimal digits. Follow these steps:

  1. Use the following command to print out the certificate information for your JAR file, replacing myjar.jar with the name of your JAR file:

    keytool -printcert -jarfile myjar.jar | more
  2. At the beginning of the output, find Signer #1

  3. In the Certificate fingerprints section under Signer #1, find the line that begins with SHA256.

    The text that follows the SHA256 identifier contains 32 pairs of hexadecimal numbers separated by colons.

  4. Copy the string that follows the SHA256 identifier to a text editor and remove the colons.

    The string that you create by removing the colons is the hash value to use for the hash attribute of the certificate element.

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:

To view the active rule set, see the Security section of Java Control Panel.

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:

Examples

The following rule set allows all RIAs from https://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="https://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. The following rule set allows all RIAs from https://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="https://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. The following rule set allows RIAs from https://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 https://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="https://host.example.com/games" />
    <action permission="default" />
  </rule>

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

The following rule set modifies the previous rule set and allows the RIA named Solitaire from https://host.example.com/games to run with default processing. Other RIAs from https://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="https://host.example.com/games" />
    <action permission="default" />
  </rule>

  <rule>
    <id location="https://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>

If you want 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. The following rule set 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> 

Copyright © 1993, 2014, Oracle and/or its affiliates. All rights reserved.