JAR File Manifest Attributes for Security

Java Rich Internet Applications Guide > Security > JAR File Manifest Attributes for Security

Contents

Overview

The JAR file manifest contains information about the contents of the JAR file, including security and configuration information. Use the manifest attributes described in this section to enhance the security of running RIAs from a browser. Add the attributes to the manifest before the JAR file is signed. See Modifying a Manifest File in the Java Tutorial for information on adding attributes to the JAR manifest file.

Note: These attributes apply to signed applets and Java Web Start applications. These attributes are ignored for stand-alone Java applications.

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. Use this 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.

If the Security Level slider in the Java Control Panel is set to Very High or High, the Permissions attribute is required in the main JAR file for the RIA. If the attribute is not present, then the RIA is blocked.

For the Medium security level, if the Permissions attribute is not present, then the security prompt contains a yellow warning about the missing attribute, and the permissions level requested by the RIA is used.

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.

Note: 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.

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.

Value	Matches	Does Not Match
*	All domains
https://*.example.com	https://a.example.com https://a.b.example.com	http://a.example.com http://a.b.example.com
www.example.com	https://www.example.com, http://www.example.com	http://example.com http://example.net
www.example.com:8085	https://www.example.com:8085, http://www.example.com:8085	http://www.example.com
*.example.com	https://a.example.com, http://a.example.com https://a.b.example.com, http://a.b.example.com https://example.com, http://example.com	http://example.net
127.0.0.1	http://127.0.0.1 http://127.0.0.1:8080 http://127.0.0.1:80	http://localhost
127.0.0.1:8080	http://127.0.0.1:8080	http://127.0.0.1 http://127.0.0.1:80

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.

Application-Name Attribute

The Application-Name attribute is used in security prompts to provide a title for your signed RIA. Use of this attribute is recommended to help 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 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. Titles are not shown for unsigned RIAs.

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: https://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 JNLP file or HTML page that starts the RIA.

See Codebase Attribute for a description of the values that are allowed.

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 (*) is specified as the value for the Caller-Allowable-Codebase attribute, then calls from JavaScript code to your RIA show a security warning, and users have the choice to allow the call or block the call. An option to remember the choice is also provided, and if selected, the warning is no longer shown when the RIA is launched.

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.

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.

Additional Information

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

See Preventing RIAs from Being Repurposed for information on using manifest attributes to ensure that the correct permissions level and code base are used.

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