8347946: Add API note that caller should validate/trust signers to the getCertificates and getCodeSigners methods of JarEntry and JarURLConnection

Reviewed-by: lancea, jpai

src/java.base/share/classes/java/net/JarURLConnection.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2025, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -301,9 +301,23 @@ public abstract class JarURLConnection extends URLConnection {
      * can only be called once
      * the connection has been completely verified by reading
      * from the input stream until the end of the stream has been
-     * reached. Otherwise, this method will return {@code null}
+     * reached. Otherwise, this method will return {@code null}.
      *
-     * @return the Certificate object for this connection if the URL
+     * <p>The returned certificate array comprises all the signer certificates
+     * that were used to verify this entry. Each signer certificate is
+     * followed by its supporting certificate chain (which may be empty).
+     * Each signer certificate and its supporting certificate chain are ordered
+     * bottom-to-top (i.e., with the signer certificate first and the (root)
+     * certificate authority last).
+     *
+     * @apiNote
+     * The verification process does not include validating or establishing
+     * trust in the code signers. A caller should perform additional checks,
+     * such as using a {@link java.security.cert.CertPathValidator} to
+     * validate each signer's certificate chain, and determining whether
+     * to trust the entry signed by the signers.
+     *
+     * @return the Certificate objects for this connection if the URL
      * for it points to a JAR file entry, null otherwise.
      *
      * @throws    IOException if getting the JAR entry causes an

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2025, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -97,6 +97,9 @@ public class JarEntry extends ZipEntry {
      * from the entry input stream until the end of the stream has been
      * reached. Otherwise, this method will return {@code null}.
      *
+     * <p>It is recommended to use the {@link getCodeSigners} method instead,
+     * which returns an array of {@code CodeSigner}s.
+     *
      * <p>The returned certificate array comprises all the signer certificates
      * that were used to verify this entry. Each signer certificate is
      * followed by its supporting certificate chain (which may be empty).
@@ -104,8 +107,16 @@ public class JarEntry extends ZipEntry {
      * bottom-to-top (i.e., with the signer certificate first and the (root)
      * certificate authority last).
      *
+     * @apiNote
+     * The verification process does not include validating or establishing
+     * trust in the code signers. A caller should perform additional checks,
+     * such as using a {@link java.security.cert.CertPathValidator} to
+     * validate each signer's certificate chain, and determining whether
+     * to trust the entry signed by the signers.
+     *
      * @return the {@code Certificate} objects for this entry, or
      * {@code null} if none.
+     *
      */
     public Certificate[] getCertificates() {
         return certs == null ? null : certs.clone();
@@ -121,6 +132,13 @@ public class JarEntry extends ZipEntry {
      * <p>The returned array comprises all the code signers that have signed
      * this entry.
      *
+     * @apiNote
+     * The verification process does not include validating or establishing
+     * trust in the code signers. A caller should perform additional checks,
+     * such as using a {@link java.security.cert.CertPathValidator} to
+     * validate each signer's certificate chain, and determining whether
+     * to trust the entry signed by the signers.
+     *
      * @return the {@code CodeSigner} objects for this entry, or
      * {@code null} if none.
      *

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2025, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -93,7 +93,7 @@ import java.util.zip.ZipFile;
  * multi-release jar file, the content of a versioned entry is verified against
  * its own signature and {@link JarEntry#getCodeSigners()} returns its own signers.
  *
- * Please note that the verification process does not include validating the
+ * <p>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.