26.1 Permissions Attribute

The Permissions attribute is used to verify that the permissions level requested by the RIA when it runs matches the permissions level that was set when the JAR file was created. This attribute is required in the manifest of the main JAR file for the RIA, secondary JAR files and extensions are not required to have the Permissions attribute. If the attribute is not present in the main JAR file, then the RIA is blocked.

Use the Permissions attribute to help prevent someone from re-deploying an application that is signed with your certificate and running it at a different privilege level. Set this attribute to one of the following values:

• sandbox - Indicates that the RIA runs in the security sandbox and does not require additional permissions.

• all-permissions - Indicates that the RIA requires access to the user's system resources.

For Java Web Start applications and applets that use JNLP, the value of the Permissions attribute must match the permissions level requested in the JNLP file, or match the default permission if no permissions level is requested. Otherwise, an error is shown and the RIA is blocked. See Structure of the JNLP File for information on the security element that is used to request the permissions level. If the element is not present, the permissions level defaults to sandbox.

For applets that do not use JNLP, the value of the Permissions attribute must match the permissions level requested in the applet tag. Otherwise, an error is shown and the RIA is blocked. If the applet tag does not contain a permissions level, then signed applets run with the permissions level set by the Permissions attribute. See Deploying with the Applet Tag for information on setting the permissions level in the applet tag.

26.2 Codebase Attribute

The Codebase attribute is used to restrict the code base of the JAR file to specific domains. Use this attribute to prevent someone from re-deploying your application on another website for malicious purposes.

Set this attribute to either the domain name or IP address where the JAR file for the application is located. The protocol and port number can also be included. For multiple locations, separate the values with a space. An asterisk (*) can be used as a wildcard only at the beginning of the domain name, and cannot be used with only a top-level domain, such as *.com. The following table shows sample values and what they match.

The value of the Codebase attribute must match the location of the JAR file for the RIA. Otherwise, an error is shown and the RIA is blocked. If the attribute is not present, a warning is written to the Java Console and the code base specified for the applet tag or JNLP file is used.

26.3 Application-Name Attribute

The Application-Name attribute provides a title for your signed RIA. The title of a RIA is used in security prompts when the user is prompted for permission to run the RIA. A meaningful title helps users make the decision to trust and run the RIA. The value can be any valid string, for example:

Application-Name: Hello World 

If the RIA has an unsigned JNLP file or is started with the applet tag in a web page, use the Application-Name attribute to ensure that users are shown a valid title from a signed source. If the Application-Name attribute is not present in the JAR file manifest, a warning is written to the Java Console and the value for the Main-Class attribute is used. If neither attribute is present in the manifest, no title is shown in the security prompts.

If a RIA has a signed JNLP file, the title shown in the security prompts is taken from the title element in the JNLP file. The Application-Name attribute is ignored.

Titles are not shown for unsigned RIAs.

26.4 Application-Library-Allowable-Codebase Attribute

The Application-Library-Allowable-Codebase attribute identifies the locations where your signed RIA is expected to be found. This attribute is used to determine what is listed in the Location field for the security prompt that is shown to users when the JAR file for your RIA is in a different location than the JNLP file or HTML page that starts your RIA. If the files are not in the locations identified, the RIA is blocked. Set this attribute to the domains where the JAR file, JNLP file, and HTML page are located. To specify more than one domain, separate the domains by a space, for example:

Application-Library-Allowable-Codebase: //host.example.com *.samplehost.com 

If the Application-Library-Allowable-Codebase attribute is present and matches the location from which the RIA is started, then a single host is listed in the Location field for the prompt and the option to hide future prompts is provided. If this attribute is present and the files are accessed from a location not included for the attribute, then the RIA is blocked. If this attribute is not present, then multiple hosts that correspond to the locations of the JAR file and the JNLP file or HTML page are listed in the Location field for the prompt. When multiple hosts are shown, the user is not given the option to hide future prompts. Use of this attribute is recommended so the files for the RIA are accessed only from known locations.

This attribute is not needed if the JAR file for the RIA is in the same location as the HTML page that starts the RIA. The attribute is needed if Java Web Start is used with a downloaded JNLP file that does not contain the href attribute set to the original location of the JNLP file. The downloaded JNLP file without the href attribute is treated as a local file, and therefore does not match the location of the JAR file for the RIA.

See Codebase Attributefor a description of the values that are allowed.

26.5 Caller-Allowable-Codebase Attribute

The Caller-Allowable-Codebase attribute is used to identify the domains from which JavaScript code can make calls to your RIA without security prompts. Set this attribute to the domain that hosts the JavaScript code. If a call is made from JavaScript code that is not located in a domain specified by the Caller-Allowable-Codebase attribute, the call is blocked. To specify more than one domain, separate the domains by a space, for example:

Caller-Allowable-Codebase: host.example.com 127.0.0.1 

If the Caller-Allowable-Codebase attribute is not present, calls from JavaScript code to your RIA show a security warning, and users have the choice to allow the call or block the call. For unsigned RIAs, JavaScript code that requires access to the RIA must be in the same location as the main JAR file for your RIA, otherwise, the user is prompted to allow access. Security prompts are shown for each Applet classLoader instance.

See Codebase Attribute for a description of the values that are allowed. If a stand-alone asterisk (*) or an asterisk used with a top-level domain such as *.org is specified as the value for the Caller-Allowable-Codebase attribute, then calls from JavaScript code to your RIA show a security warning. Users have the choice to allow the call or block the call. An option to remember the choice is also provided. If the user chooses to remember the choice, no further warning messages are shown for the same RIA when it receives calls from JavaScript code from the same source.

26.6 Entry-Point Attribute

The Entry-Point attribute is used to identify the classes that are allowed to be used as entry points to your RIA. Identifying the entry points helps to prevent unauthorized code from being run when a JAR file has more than one class with a main() method, multiple Applet classes, or multiple JavaFX Application classes. Set this attribute to the fully qualified class name that can be used as the entry point for the RIA. To specify more than one class, separate the classes by a space, for example:

Entry-Point: apps.test.TestUI apps.test.TestCLI

If the JAR manifest is signed and the main-class or applet-class entry point specified in the JNLP file or application descriptor differs from the class specified for the Entry-Point attribute, then the RIA is blocked. If the Entry-Point attribute is not present, any class with a main() method, or any Applet or JavaFX Application class in the JAR file can be used to start your RIA.

26.7 Trusted-Only Attribute

The Trusted-Only attribute is used to prevent untrusted classes or resources from being loaded for an applet or application. Set the value of the attribute to true, for example:

Trusted-Only: true

This attribute prevents a privileged application or applet from being repurposed with untrusted components. All classes and resources in the application or applet must be signed and request all permissions.

26.8 Trusted-Library Attribute

The Trusted-Library attribute is used for applications and applets that are designed to allow untrusted components. No warning dialog is shown and an application or applet can load JAR files that contain untrusted classes or resources. Set the value of the attribute to true, for example:

Trusted-Library: true

This attribute prevents components in a privileged application or applet from being repurposed with untrusted components. All classes and resources in a JAR file containing this manifest attribute must be signed and request all permissions.

In a mixed code application or applet, all privileged classes and resources must be included in JAR files that contain the Trusted-Library attribute. This attribute is used for calls between privileged Java code sandbox Java code. If you have JavaScript code that calls Java code, see Caller-Allowable-Codebase Attribute.

All trusted library JARs are loaded into a separate dedicated class loader that is unique to the application or applet instance. This Trusted-Library loader is now the parent of the normal Web Start or applet class loader. For backwards compatibility with the original search order, both loaders cooperate to implement a common class path. Consistent with prior releases, JAR files use lazy download and are opened as needed to find requested classes and resources.

Code in a JAR file that is to be marked with the Trusted-Library manifest attribute may need to be modified slightly if it uses calls that are class loader dependent, such as the single parameter version of Class.forName(), Class.getResource(), and Class.getResourceAsStream(), some variants of java.util.ResourceBundle.getBundle(), and any other methods that operate relative to their immediate caller's defining loader. Changes only need to be made if the requested class or resource might be found in a JAR file that is not a Trusted-Library (and is therefore loaded by the normal Web Start or applet class loader).

Code in a Trusted-Library can look up the normal loader by invoking Thread.currentThread().getContextClassLoader(). Note, however, that there are uncommon circumstances in which getContextClassLoader() may return null. For example, this may happen when the garbage collector uses a JRE system thread to invoke the Object.finalize() method of an unreachable instance.

If you need to convert class to Class.getResource() or Class.getResourceAsStream() to their ClassLoader equivalents, remember to adjust the string parameter as described by the documentation for those two methods. If the original resource name began with '/', then it was an absolute name and the leading '/' simply needs to be removed. Otherwise, determine if the class instance which was the target of the getResource call is in a named package. If it is an array you should first determine the underlying component type of the array. Invoke Class.getName() on the class or component type instance. If the class name contains any '.' characters, it is in a named package that will need to be prepended to the original resource name. Determine the package name by removing any characters after, and including, the trailing '.' character. Next, replace any remaining '.' characters with '/' characters. Finally, add a trailing '/' and append the original resource name string. This new string can now be passed to the ClassLoader version of the getResource() or getResourceAsStream() methods.

Generally, care must be taken to ensure that the code in the trusted library is written in a careful and secure manner and is otherwise compatible with being loaded in a separate class loader instance from any remaining jars that are part of the application and are loaded by the normal loader.

26.9 Preventing RIAs from Being Repurposed

The Permissions attribute and the Codebase attribute were introduced in the JDK 7u25 release to defend RIAs against unauthorized code repurposing.

Without the Permissions attribute, it might be possible for an attacker to exploit a user by re-deploying an application that is signed with your certificate, and running the application at a different privilege level.

If the Codebase attribute does not specify a secure server, such as HTTPS, some risk exists that your code could be repurposed in Man-in-the-Middle (MITM) attack schemes.

The following code example shows the attributes to add to the manifest if you have a RIA that runs in the security sandbox and is expected to be accessed from //example.com:

Permissions: sandbox
Codebase: //example.com

If the RIA is also available from example.backup.com:8080, include both domains for the Codebase attribute:

Codebase: //example.com example.backup.com:8080

26.10 Additional Information

See Chapter 27, "Mixing Privileged Code and Sandbox Code" for information on using manifest attributes to manage calls from untrusted code.

For information on adding attributes to the JAR manifest file, see Modifying a Manifest File in the Java Tutorial.