In many cases, JAR files are not just simple archives of java classes files and/or resources. They are used as building blocks for applications and extensions. The META-INF directory, if it exists, is used to store package and extension configuration data, including security, versioning, extension and services.
Groups of name-value pairs are known as a "section". Sections are separated from other sections by empty lines.
Binary data of any form is represented as base64. Continuations are required for binary data which causes line length to exceed 72 bytes. Examples of binary data are digests and signatures.
Implementations shall support header values of up to 65535 bytes.
All the specifications in this document use the same grammar in which terminal symbols are shown in fixed width font and non-terminal symbols are shown in italic type face.
; Also: To prevent mangling of files sent via straight
e-mail, no
; header will start with the four letters "From".
Non-terminal symbols defined in the above specification will be referenced in the following specifications.
The main section contains security and configuration information about the JAR file itself, as well as the application or extension that this JAR file is a part of. It also defines main attributes that apply to every individual manifest entry. No attribute in this section can have its name equal to "Name". This section is terminated by an empty line.
The individual sections define various attributes for packages or files contained in this JAR file. Not all files in the JAR file need to be listed in the manifest as entries, but all files which are to be signed must be listed. The manifest file itself must not be listed. Each section must start with an attribute with the name as "Name", and the value must be a relative path to the file, or an absolute URL referencing data outside the archive.
If there are multiple individual sections for the same file entry, the attributes in these sections are merged. If a certain attribute have different values in different sections, the last one is recognized.
Attributes which are not understood are ignored. Such attributes may include implementation specific information used by applications.
In the above specification, attributes that can appear in the
main section are referred to as main attributes, whereas attributes
that can appear in individual sections are referred to as per-entry
attributes. Certain attributes can appear both in the main section
and the individual sections, in which case the per-entry attribute
value overrides the main attribute value for the specified entry.
The two types of attributes are defined as follows.
Manifest-Version: 1.0 Created-By: 1.2 (Sun Microsystems Inc.) Sealed: true Name: foo/bar/ Sealed: false
It means that all the packages archived in a.jar are sealed, except that package foo.bar is not.
The per-entry attributes fall into the following groups:
java.security API. Every file
entry, including non-signature related files in the
META-INF directory, will be signed if the JAR file is
signed by the jarsigner tool. The signature related files are:
META-INF/MANIFEST.MFMETA-INF/*.SFMETA-INF/*.DSAMETA-INF/*.RSAMETA-INF/SIG-*META-INF
subdirectories, they are not considered signature-related.
Case-insensitive versions of these filenames are reserved and will
also not be signed.
Subsets of a JAR file can be signed by using the
java.security API. A signed JAR file is exactly the
same as the original JAR file, except that its manifest is updated
and two additional files are added to the META-INF
directory: a signature file and a signature block file. When
jarsigner is not used, the signing program has to construct both
the signature file and the signature block file.
For every file entry signed in the signed JAR file, an individual manifest entry is created for it as long as it does not already exist in the manifest. Each manifest entry lists one or more digest attributes and an optional Magic attribute.
.SF. The major part of the file is similar to the
manifest file. It consists of a main section which includes
information supplied by the signer but not specific to any
particular jar file entry. In addition to the
Signature-Version and Created-By
attributes (see Main Attributes),
the main section can also include the following security
attributes:
java.security.MessageDigest algorithm): The value
of this attribute is the digest value of the main attributes of the
manifest.java.security.MessageDigest algorithm): The value of
this attribute is the digest value of the entire manifest.Paths or URLs appearing in the manifest file but not in the signature file are not used in the calculation.
Verify the signature over the signature file when the manifest is first parsed. For efficiency, this verification can be remembered. Note that this verification only validates the signature directions themselves, not the actual archive files.
If an x-Digest-Manifest attribute exists in the
signature file, verify the value against a digest calculated over
the entire manifest. If more than one
x-Digest-Manifest attribute exists in the signature
file, verify that at least one of them matches the calculated
digest value.
If an x-Digest-Manifest attribute does not exist in
the signature file or none of the digest values calculated in the
previous step match, then a less optimized verification is
performed:
If an x-Digest-Manifest-Main-Attributes entry
exists in the signature file, verify the value against a digest
calculated over the main attributes in the manifest file. If this
calculation fails, then JAR file verification fails. This decision
can be remembered for efficiency. If an
x-Digest-Manifest-Main-Attributes entry does not exist
in the signature file, its nonexistence does not affect JAR file
verification and the manifest main attributes are not verified.
Verify the digest value in each source file information section in the signature file against a digest value calculated against the corresponding entry in the manifest file. If any of the digest values don't match, then JAR file verification fails.
One reason the digest value of the manifest file that is stored
in the x-Digest-Manifest attribute may not equal the
digest value of the current manifest file is that one or more files
were added to the JAR file (using the jar tool) after the signature
(and thus the signature file) was generated. When the jar tool is
used to add files, the manifest file is changed (sections are added
to it for the new files), but the signature file is not. A
verification is still considered successful if none of the files
that were in the JAR file when the signature was generated have
been changed since then, which is the case if the digest values in
the non-header sections of the signature file equal the digest
values of the corresponding sections in the manifest file.
For each entry in the manifest, verify the digest value in the manifest file against a digest calculated over the actual data referenced in the "Name:" attribute, which specifies either a relative file path or URL. If any of the digest values don't match, then JAR file verification fails.
Example manifest file:
Manifest-Version: 1.0 Created-By: 1.7.0 (Sun Microsystems Inc.) Name: common/class1.class SHA-256-Digest: (base64 representation of SHA-256 digest) Name: common/class2.class SHA1-Digest: (base64 representation of SHA1 digest) SHA-256-Digest: (base64 representation of SHA-256 digest)The corresponding signature file would be:
Signature-Version: 1.0 SHA-256-Digest-Manifest: (base64 representation of SHA-256 digest) SHA-256-Digest-Manifest-Main-Attributes: (base64 representation of SHA-256 digest) Name: common/class1.class SHA-256-Digest: (base64 representation of SHA-256 digest) Name: common/class2.class SHA-256-Digest: (base64 representation of SHA-256 digest)
The Magic attribute is optional but it is required that a parser understand the value of an entry's Magic key if it is verifying that entry's signature.
The value or values of the Magic attribute are a set of comma-separated context-specific strings. The spaces before and after the commas are ignored. Case is ignored. The exact meaning of the magic attributes is application specific. These values indicate how to compute the hash value contained in the manifest entry, and are therefore crucial to the proper verification of the signature. The keywords may be used for dynamic or embedded content, multiple hashes for multilingual documents, etc.
Here are two examples of the potential use of Magic attribute in the manifest file:
Name: http://www.example-scripts.com/index#script1
SHA-256-Digest: (base64 representation of SHA-256 hash)
Magic: JavaScript, Dynamic
Name: http://www.example-tourist.com/guide.html
SHA-256-Digest: (base64 representation of SHA-256 hash)
SHA-256-Digest-French: (base64 representation of SHA-256 hash)
SHA-256-Digest-German: (base64 representation of SHA-256 hash)
Magic: Multilingual
In the first example, these Magic values may indicate that the result of an http query is the script embedded in the document, as opposed to the document itself, and also that the script is generated dynamically. These two pieces of information indicate how to compute the hash value against which to compare the manifest's digest value, thus comparing a valid signature.
In the second example, the Magic value indicates that the document retrieved may have been content-negotiated for a specific language, and that the digest to verify against is dependent on which language the document retrieved is written in.
.SF
signature file. These are binary files not intended to be
interpreted by humans.
Digital signature files have the same filenames as the .SF files but different extensions. The extension varies depending on the type of digital signature.
.RSA (PKCS7 signature, SHA-256 + RSA).DSA (PKCS7 signature, DSA)META-INF directory and have the
prefix "SIG-". The corresonding signature file
(.SF file) must also have the same prefix.
For those formats that do not support external signed data, the
file shall consist of a signed copy of the .SF file.
Thus some data may be duplicated and a verifier should compare the
two files.
Formats that support external data either reference the
.SF file, or perform calculations on it with implicit
reference.
Each .SF file may have multiple digital signatures,
but those signatures should be generated by the same legal
entity.
File name extensions may be 1 to 3 alphanum characters. Unrecognized extensions are ignored.
The existing jar tool is enhanced to be able to examine a list of jar files and generate directory information as to which classes and resources reside in which jar file. This directory information is stored in a simple text file named INDEX.LIST in the META-INF directory of the root jar file. When the classloader loads the root jar file, it reads the INDEX.LIST file and uses it to construct a hash table of mappings from file and package names to lists of jar file names. In order to find a class or a resource, the class loader queries the hashtable to find the proper jar file and then downloads it if necessary.
Once the class loader finds a INDEX.LIST file in a particular jar file, it always trusts the information listed in it. If a mapping is found for a particular class, but the class loader fails to find it by following the link, an InvalidJarIndexException is thrown. When this occurs, the application developer should rerun the jar tool on the extension to get the right information into the index file.
To prevent adding too much space overhead to the application and to speed up the construction of the in-memory hash table, the INDEX.LIST file is kept as small as possible. For classes with non-null package names, mappings are recorded at the package level. Normally one package name is mapped to one jar file, but if a particular package spans more than one jar file, then the mapped value of this package will be a list of jar files. For resource files with non-empty directory prefixes, mappings are also recorded at the directory level. Only for classes with null package name, and resource files which reside in the root directory, will the mapping be recorded at the individual file level.
The UTF-8 encoding is used to support non ASCII characters in
file or package names in the index file.
Files in the META-INF/services directory are service provider configuration files. A service is a well-known set of interfaces and (usually abstract) classes. A service provider is a specific implementation of a service. The classes in a provider typically implement the interfaces and subclass the classes defined in the service itself. Service providers may be installed in an implementation of the Java platform in the form of extensions, that is, jar files placed into any of the usual extension directories. Providers may also be made available by adding them to the applet or application class path or by some other platform-specific means.
A service is represented by an abstract class. A provider of a given service contains one or more concrete classes that extend this service class with data and code specific to the provider. This provider class will typically not be the entire provider itself but rather a proxy that contains enough information to decide whether the provider is able to satisfy a particular request together with code that can create the actual provider on demand. The details of provider classes tend to be highly service-specific; no single class or interface could possibly unify them, so no such class has been defined. The only requirement enforced here is that provider classes must have a zero-argument constructor so that they may be instantiated during lookup.
A service provider identifies itself by placing a provider-configuration file in the resource directory META-INF/services. The file's name should consist of the fully-qualified name of the abstract service class. The file should contain a newline-separated list of unique concrete provider-class names. Space and tab characters, as well as blank lines, are ignored. The comment character is '#' (0x23); on each line all characters following the first comment character are ignored. The file must be encoded in UTF-8.
public abstract CharEncoder getEncoder(String
encodingName);public abstract CharDecoder getDecoder(String
encodingName);Each method returns an appropriate object or null if it cannot translate the given encoding. Typical CharCodec providers will support more than one encoding.
If sun.io.StandardCodec is a provider of the CharCodec service then its jar file would contain the file META-INF/services/java.io.spi.CharCodec. This file would contain the single line:
sun.io.StandardCodec # Standard codecs for the platform
To locate an encoder for a given encoding name, the internal I/O code would do something like this:
CharEncoder getEncoder(String encodingName) {
Iterator ps = Service.providers(CharCodec.class);
while (ps.hasNext()) {
CharCodec cc = (CharCodec)ps.next();
CharEncoder ce = cc.getEncoder(encodingName);
if (ce != null)
return ce;
}
return null;
}
The provider-lookup mechanism always executes in the security context of the caller. Trusted system code should typically invoke the methods in this class from within a privileged security context.
The manifest for an application can specify one or more relative URLs referring to the JAR files and directories for other libraries that it requires. These relative URLs are treated relative to the code base from which the containing application was loaded.
An application (or, more generally, a JAR file) specifies the
relative URLs of the libraries that it requires with the manifest attribute
Class-Path. This attribute lists the URLs to search for
implementations of other libraries if they cannot be found
on the host Java virtual machine.
These
relative URLs may include JAR files and directories for any
libraries or resources needed by the application. Relative URLs
not ending with a slash (/) are assumed to refer to JAR files. For example:
Class-Path: servlet.jar infobus.jar acme/beans.jar images/
At most one Class-Path header may be specified in a JAR
file's manifest.
Currently, the URLs must be relative to the code base of the JAR file for security reasons. Thus, remote optional packages will originate from the same code base as the application.
Each relative URL is resolved against the code base from which the containing application or library was loaded. If the resulting URL is invalid or refers to a resource that cannot be found, then it is ignored.
The resulting URLs are used to extend the class path for the application, applet, or servlet by inserting the URLs in the class path immediately following the URL of the containing JAR file. Any duplicate URLs are omitted. For example, given the following class path:
a.jar b.jar
Suppose b.jar contained the following
Class-Path manifest attribute:
Class-Path: x.jar a.jar
As a result, the resulting application class path would be the following:
a.jar b.jar x.jar
If x.jar had dependencies of its own, then these
would be added according to the same rules for each
subsequent URL. In the actual implementation, JAR file dependencies
are processed lazily so that the JAR files are not opened
until needed.
JAR files and packages can be optionally sealed so that an package can enforce consistency within a version.
A package sealed within a JAR specifies that all classes defined
in that package must originate from the same JAR. Otherwise, a
SecurityException is thrown.
A sealed JAR specifies that all packages defined by that JAR are sealed unless overridden specifically for a package.
A sealed package is specified through the manifest attribute,
Sealed, whose value is true or false
(case irrelevant). For example:
Name: javax/servlet/internal/ Sealed: true
This specifies that the javax.servlet.internal package is
sealed, and that all classes in that package must be loaded from
the same JAR file.
If this attribute is missing, then the package sealing attribute is that of the containing JAR file.
A sealed JAR is specified via the same manifest header,
Sealed, with the value again of either true or
false. For example:
Sealed: true
This specifies that all packages in this archive are sealed unless
explicitly overridden for a particular package with the
Sealed attribute in a manifest entry.
If this attribute is missing, the JAR file is assumed to not be sealed, for backwards compatibility. The system then defaults to examining package headers for sealing information.
Package sealing is also important for security because it restricts access to package-protected members to only those classes defined in the package that originated from the same JAR file.
An unnamed package is not sealable, so classes that are to be sealed must be placed in their own packages.
Package java.util.jar
Package java.security
Package java.util.zip
