Summary

Update the specification of java.util.jar.JarInputStream to make it clear that it only reads the JAR file manifest when it is at the beginning of the stream.

Problem

The JarInputStream class description does not specify the circumstances as to when the JarInputStream::getManifest and JarInputStream::getNext{jar]Entry methods will return the JAR file's Manfiest.

The behavior dates back to JDK 1.2 when JarInputStream was first added to the JDK.

Solution

Update the class description to specify that the manifest is only found when it is at the beginning of the JAR file.

Update the method description of JarInputStream::getManifest to also make it clear that the manifest is only found when it is at the beginning of the JAR file.

Specification

The class description will be updated as follows:

The JarInputStream class, which extends ZipInputStream, is used to read the contents of a JAR file from an input stream. It provides support for reading an optional Manifest entry. The Manifest can be used to store meta-information about the JAR file and its entries.

Accessing the Manifest

The getManifest method is used to return the Manifest from the entry META-INF/MANIFEST.MF when it is the first entry in the stream (or the second entry if the first entry in the stream is META-INF/ and the second entry is META-INF/MANIFEST.MF).

The getNextJarEntry() and getNextEntry() methods are used to read JAR file entries from the stream. These methods skip over the Manifest (META-INF/MANIFEST.MF) when it is at the beginning of the stream. In other words, these methods do not return an entry for the Manifest when the Manifest is the first entry in the stream. If the first entry is META-INF/ and the second entry is the Manifest then both are skipped over by these methods. Whether these methods skip over the Manifest when it appears later in the stream is not specified.

Signed JAR Files

A JarInputStream verifies the signatures of entries in a Signed JAR file when:

• The Manifest is the first entry in the stream (or the second entry if the first entry in the stream is META-INF/ and the second entry is META-INF/MANIFEST.MF).
• All signature-related entries immediately follow the Manifest

Once the JarEntry has been completely verified, which is done by reading until the end of the entry's input stream, JarEntry.getCertificates() may be called to obtain the certificates for this entry and JarEntry.getCodeSigners() may be called to obtain the signers.

It is important to note that the verification process does not include validating the signer's certificate. A caller should inspect the return value of JarEntry.getCodeSigners() to further determine if the signature can be trusted.

API Note

If a JarEntry is modified after the JAR file is signed, a SecurityException will be thrown when the entry is read.

The getManifest description has been updated as follows:

public Manifest getManifest()

Returns the Manifest for this JAR file when it is the first entry in the stream (or the second entry if the first entry in the stream is META-INF/ and the second entry is META-INF/MANIFEST.MF), or null otherwise.

Returns:

the Manifest for this JAR file, or null otherwise.