Java Rich Internet Applications Guide > Security > JAR File Manifest Attributes for Security
Contents
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.
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.
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 |
| 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.
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.
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.
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.
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.
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.
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.
