Summary

The JarFile API specification does not specify explicitly how the versioned jar entry is verified when the signed multi-release jar file is opened and processed as a "multi-release-signed" JarFile. This CSR is proposing to update the spec to clarity that the versioned entry is being verified against its own signature and signers in this situation.

Problem

As described in the Summary Section the current specification is unclear on how the versioned entry is verified when the signed multi-release jar file is opened as a "multi-release-signed" JarFile. This might cause concern and /or confusion in real world multi-release-signed jar file use scenario, especially when the versioned entry and its associated base entry have different signatures (including situation such as the base entry is signed but the versioned entry is not signed, or vice versa) and or different signers.

Solution

The proposed update is to clarify the class API specification that the versioned jar entry is verified against its own signature with its own signers when associated to a corresponding base entry.

Specification

src/java.base/share/classes/java/util/jar/JarFile.java

  * by invoking the {@link JarFile#JarFile(File, boolean, int, Runtime.Version)}
  * constructor with the value {@code Runtime.version()} assigned to the last
  * argument.  This assures that classes compatible with the major
  * version of the running JVM are loaded from multi-release jar files.
  *
- * <p>If the verify flag is on when opening a signed jar file, the content of
- * the file is verified against its signature embedded inside the file. Please
- * note that the verification process does not include validating the signer's
- * certificate. A caller should inspect the return value of
+ * <p> If the {@code verify} flag is on when opening a signed jar file, the content
+ * of the jar entry is verified against the signature embedded inside the manifest
+ * that is associated with its {@link JarEntry#getRealName() path name}. For a
+ * multi-release jar file, the content of a versioned entry is verfieid against
+ * its own signature and {@link JarEntry#getCodeSigners()} returns its own signers.
+ *
+ * Please note that the verification process does not include validating the
+ * signer's certificate. A caller should inspect the return value of
  * {@link JarEntry#getCodeSigners()} to further determine if the signature
  * can be trusted.
  *
  * <p> Unless otherwise noted, passing a {@code null} argument to a constructor
  * or method in this class will cause a {@link NullPointerException} to be