GH-699: hash/digest verification of URL dependencies (#701)

This change introduces a new set of options that can be specified when
referencing protoc plugins by URL that allow users to specify the
expected digest of the resource to be downloaded. If the downloaded
resource does not match the digest, then the plugins are not executed,
and the build will fail with an error.

The aim is to allow users to verify that their dependencies have not
been tampered with prior to running anything. This is already performed
internally by Maven on Maven-based dependencies.

Digests will be able to be specified in the format
`md5:09f7e02f1290be211da707a266f153b3`,
`sha256:66a045b452102c59d840ec097d59d9467e13a3f34f6494e539ffd32c1bb35f18`,
etc for any supported JVM `MessageDigest` (this is usually a small set
including MD5, SHA-1, SHA-256, and SHA-512).

Users should consult the documentation for their Java version to see
which MessageDigest format are supported for their platform.

Users may _in theory_ be able to extend this by adding bouncy castle to
the classpath, although this will not be tested nor verified in this PR.

---

## TODO list

- [x] Implement Digest class for parsing, holding, comparing digests
- [x] Unit test Digest class
- [x] Implement Plexus DigestConverter to allow parsing digests to
Digest objects in pom.xml configuration blocks
- [x] Unit test DigestConverter class
- [x] Remove all references of `*.utils.Digests`, and replace with this
new `Digest` class
- [x] Add optional digest attribute to URL plugins
- [x] Validate digest of URL resource if the digest is provided in the
configuration
- [x] Add optional digest for protoc executable if specified as a URL.
- [x] Report user-friendly errors if digests do not match
- [x] Implement new integration tests
- [x] Minor version bump
- [x] Update documentation for MOJO goals
- [x] Update user guide markdown documentation

Closes GH-699.

Author: ascopes

pom.xml

@@ -21,7 +21,7 @@
 
   <groupId>io.github.ascopes</groupId>
   <artifactId>protobuf-maven-plugin-parent</artifactId>
-  <version>3.4.3-SNAPSHOT</version>
+  <version>3.5.0-SNAPSHOT</version>
 
   <name>Protobuf Maven Plugin Parent</name>
   <description>Parent POM for the Protobuf Maven Plugin.</description>

protobuf-maven-plugin/pom.xml

@@ -22,7 +22,7 @@
   <parent>
     <groupId>io.github.ascopes</groupId>
     <artifactId>protobuf-maven-plugin-parent</artifactId>
-    <version>3.4.3-SNAPSHOT</version>
+    <version>3.5.0-SNAPSHOT</version>
   </parent>
 
   <artifactId>protobuf-maven-plugin</artifactId>

protobuf-maven-plugin/src/it/http-url-grpc-plugin/pom.xml

@@ -89,6 +89,7 @@
           <binaryUrlPlugins>
             <binaryUrlPlugin>
               <url>https://repo1.maven.org/maven2/io/grpc/protoc-gen-grpc-java/${grpc.version}/protoc-gen-grpc-java-${grpc.version}-linux-x86_64.exe</url>
+              <digest>sha256:a9f9a7987be4a37c69a85e5e8885394356fd2f1a47f843c6461da4fc99f407b3</digest>
               <!-- See https://github.com/grpc/grpc-java/issues/9179 -->
               <options>@generated=omit</options>
             </binaryUrlPlugin>

protobuf-maven-plugin/src/it/http-url-protoc/pom.xml

@@ -67,7 +67,8 @@
         <artifactId>@project.artifactId@</artifactId>
 
         <configuration>
-          <protocVersion>https://repo1.maven.org/maven2/com/google/protobuf/protoc/${protobuf.version}/protoc-${protobuf.version}-linux-x86_64.exe</protocVersion>
+          <protoc>https://repo1.maven.org/maven2/com/google/protobuf/protoc/${protobuf.version}/protoc-${protobuf.version}-linux-x86_64.exe</protoc>
+          <protocDigest>md5:6c224d84618c71e2ebb46dd9c4459aa6</protocDigest>
         </configuration>
 
         <executions>

protobuf-maven-plugin/src/it/scalapb-plugin/pom.xml

@@ -75,6 +75,7 @@
           <binaryUrlPlugins>
             <binaryUrlPlugin>
               <url>zip:https://github.com/scalapb/ScalaPB/releases/download/v${scalapb.version}/protoc-gen-scala-${scalapb.version}-linux-x86_64.zip!/protoc-gen-scala</url>
+              <digest>sha1:bca1d071820bab1ebb0ddd058e6fb621aca321c5</digest>
               <options>flat_package,grpc,scala3_sources</options>
             </binaryUrlPlugin>
           </binaryUrlPlugins>

protobuf-maven-plugin/src/main/java/io/github/ascopes/protobufmavenplugin/fs/UriResourceFetcher.java

@@ -15,7 +15,7 @@
  */
 package io.github.ascopes.protobufmavenplugin.fs;
 
-import io.github.ascopes.protobufmavenplugin.utils.Digests;
+import io.github.ascopes.protobufmavenplugin.utils.Digest;
 import io.github.ascopes.protobufmavenplugin.utils.ResolutionException;
 import java.io.BufferedInputStream;
 import java.io.BufferedOutputStream;
@@ -175,7 +175,7 @@ private Optional<Path> handleOtherUri(URI uri, String extension) throws Resoluti
   }
 
   private Path targetFile(URL url, String extension) {
-    var digest = Digests.sha1(url.toExternalForm());
+    var digest = Digest.compute("SHA-1", url.toExternalForm()).toHexString();
     var path = url.getPath();
     var lastSlash = path.lastIndexOf('/');
     var fileName = lastSlash < 0

protobuf-maven-plugin/src/main/java/io/github/ascopes/protobufmavenplugin/generation/GenerationRequest.java

@@ -20,6 +20,7 @@
 import io.github.ascopes.protobufmavenplugin.plugins.MavenProtocPlugin;
 import io.github.ascopes.protobufmavenplugin.plugins.PathProtocPlugin;
 import io.github.ascopes.protobufmavenplugin.plugins.UriProtocPlugin;
+import io.github.ascopes.protobufmavenplugin.utils.Digest;
 import java.nio.file.Path;
 import java.util.Collection;
 import java.util.List;
@@ -158,6 +159,17 @@ public interface GenerationRequest {
    */
   @Nullable String getOutputDescriptorAttachmentClassifier();
 
+  /**
+   * The digest of the {@code protoc} binary to verify, or {@code null} if
+   * no verification should take place.
+   *
+   * <p>This does not affect any verification performed by Aether.
+   *
+   * @return the digest.
+   * @since 3.5.0
+   */
+  @Nullable Digest getProtocDigest();
+
   /**
    * The version of {@code protoc} to use.
    *

protobuf-maven-plugin/src/main/java/io/github/ascopes/protobufmavenplugin/generation/ProtobufBuildOrchestrator.java

@@ -203,7 +203,7 @@ private GenerationResult handleMissingTargets(GenerationRequest request) {
   }
 
   private Path discoverProtocPath(GenerationRequest request) throws ResolutionException {
-    return protocResolver.resolve(request.getProtocVersion())
+    return protocResolver.resolve(request.getProtocVersion(), request.getProtocDigest())
         .orElseThrow(() -> new ResolutionException("Protoc binary was not found"));
   }
 

protobuf-maven-plugin/src/main/java/io/github/ascopes/protobufmavenplugin/mojo/AbstractGenerateMojo.java

@@ -30,6 +30,7 @@
 import io.github.ascopes.protobufmavenplugin.plugins.MavenProtocPluginBean;
 import io.github.ascopes.protobufmavenplugin.plugins.PathProtocPluginBean;
 import io.github.ascopes.protobufmavenplugin.plugins.UriProtocPluginBean;
+import io.github.ascopes.protobufmavenplugin.utils.Digest;
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.util.Collection;
@@ -60,11 +61,13 @@ public abstract class AbstractGenerateMojo extends AbstractMojo {
   private static final String DEFAULT_TRUE = "true";
   private static final String DEFAULT_TRANSITIVE = "TRANSITIVE";
 
+  private static final String PROTOBUF_COMPILER_DIGEST = "protobuf.compiler.digest";
   private static final String PROTOBUF_COMPILER_EXCLUDES = "protobuf.compiler.excludes";
   private static final String PROTOBUF_COMPILER_INCLUDES = "protobuf.compiler.includes";
   private static final String PROTOBUF_COMPILER_INCREMENTAL = "protobuf.compiler.incremental";
   private static final String PROTOBUF_COMPILER_VERSION = "protobuf.compiler.version";
   private static final String PROTOBUF_SKIP = "protobuf.skip";
+  private static final String PROTOC_ALIAS = "protoc";
 
   private static final Logger log = LoggerFactory.getLogger(AbstractGenerateMojo.class);
 
@@ -264,6 +267,10 @@ public AbstractGenerateMojo() {
    *       no effect, and the project-wide setting is used. If explicitly
    *       specified, then the project setting is ignored in favour of this
    *       value instead.</li>
+   *   <li>{@code digest} - an optional digest to verify the binary against.
+   *       If specified, this is a string in the format {@code sha512:1a2b3c4d...},
+   *       using any supported message digest provided by your JDK (e.g. {@code md5},
+   *       {@code sha1}, {@code sha256}, {@code sha512}, etc).</li>
    * </ul>
    *
    * @since 2.0.0
@@ -731,6 +738,22 @@ public AbstractGenerateMojo() {
   @Parameter(defaultValue = DEFAULT_FALSE)
   boolean phpEnabled;
 
+  /**
+   * Optional digest to verify {@code protoc} against.
+   *
+   * <p>Generally, you will not need to provide this, as the Maven Central
+   * {@code protoc} binaries will already be digest-verified as part of distribution.
+   * You may wish to specify this if you are using a {@code PATH}-based binary, or
+   * using a URL for {@code protoc}.
+   *
+   * <p>This is a string in the format {@code sha512:1a2b3c...}, using any
+   * message digest algorithm supported by your JDK.
+   *
+   * @since 3.5.0
+   */
+  @Parameter(property = PROTOBUF_COMPILER_DIGEST)
+  @Nullable Digest protocDigest;
+
   /**
    * Specifies where to find {@code protoc} or which version to download.
    *
@@ -768,7 +791,11 @@ public AbstractGenerateMojo() {
    *
    * @since 0.0.1
    */
-  @Parameter(required = true, property = PROTOBUF_COMPILER_VERSION)
+  @Parameter(
+      alias = PROTOC_ALIAS,
+      required = true,
+      property = PROTOBUF_COMPILER_VERSION
+  )
   String protocVersion;
 
   /**
@@ -912,7 +939,7 @@ public AbstractGenerateMojo() {
    * Override the source directories to compile from.
    *
    * <p>Leave unspecified or explicitly null/empty to use the defaults.
-   * 
+   *
    * <p><strong>Note that specifying custom directories will override the default
    * directories rather than adding to them.</strong>
    *
@@ -1037,6 +1064,7 @@ public void execute() throws MojoExecutionException, MojoFailureException {
         .outputDescriptorIncludeSourceInfo(outputDescriptorIncludeSourceInfo)
         .outputDescriptorRetainOptions(outputDescriptorRetainOptions)
         .outputDirectory(outputDirectory())
+        .protocDigest(protocDigest)
         .protocVersion(protocVersion())
         .registerAsCompilationRoot(registerAsCompilationRoot)
         .sourceDependencies(nonNullList(sourceDependencies))

protobuf-maven-plugin/src/main/java/io/github/ascopes/protobufmavenplugin/mojo/plexus/DigestConverter.java

@@ -0,0 +1,101 @@
+/*
+ * Copyright (C) 2023 - 2025, Ashley Scopes.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.github.ascopes.protobufmavenplugin.mojo.plexus;
+
+import io.github.ascopes.protobufmavenplugin.utils.Digest;
+import java.util.Collections;
+import java.util.Locale;
+import java.util.Map;
+import java.util.TreeMap;
+import java.util.regex.Pattern;
+import org.codehaus.plexus.component.configurator.ComponentConfigurationException;
+import org.codehaus.plexus.component.configurator.converters.basic.AbstractBasicConverter;
+
+/**
+ * Converter for {@link Digest}s.
+ *
+ * @author Ashley Scopes
+ * @since 3.5.0
+ */
+final class DigestConverter extends AbstractBasicConverter {
+
+  private static final Pattern PATTERN = Pattern.compile(
+      "^(?<algorithm>[-a-z0-9]+):(?<digest>[0-9a-f]+)$",
+      Pattern.CASE_INSENSITIVE
+  );
+
+  private static final Map<String, String> DIGEST_ALIASES;
+
+  static {
+    var digestAliases = new TreeMap<String, String>(String::compareToIgnoreCase);
+    digestAliases.put("sha1", "SHA-1");
+    digestAliases.put("sha224", "SHA-224");
+    digestAliases.put("sha256", "SHA-256");
+    digestAliases.put("sha384", "SHA-384");
+    digestAliases.put("sha512", "SHA-512");
+    DIGEST_ALIASES = Collections.unmodifiableMap(digestAliases);
+  }
+
+  @Override
+  public boolean canConvert(Class<?> type) {
+    return Digest.class.equals(type);
+  }
+
+  @Override
+  protected Object fromString(String str) throws ComponentConfigurationException {
+    // Users may wish to split digests into more than one line
+    // so they can satisfy tools like spotless. Support this by
+    // yanking any whitespace prior to matching the string.
+    str = removeWhitespace(str);
+    var matcher = PATTERN.matcher(str);
+
+    if (!matcher.matches()) {
+      throw new ComponentConfigurationException(
+          "Failed to parse digest '" + str + "'. "
+              +  "Ensure that the digest is in a format such as "
+              +  "'sha512:1a2b3c4d', where the digest is a hexadecimal-encoded "
+              + "string."
+      );
+    }
+
+    try {
+      var algorithm = matcher.group("algorithm");
+      algorithm = DIGEST_ALIASES.getOrDefault(algorithm, algorithm)
+          .toUpperCase(Locale.ROOT);
+
+      var digest = matcher.group("digest")
+          .toLowerCase(Locale.ROOT);
+
+      return Digest.from(algorithm, digest);
+    } catch (Exception ex) {
+      throw new ComponentConfigurationException(
+          "Failed to parse digest '" + str + "': " + ex,
+          ex
+      );
+    }
+  }
+
+  private static String removeWhitespace(String string) {
+    var sb = new StringBuilder();
+    for (var i = 0; i < string.length(); ++i) {
+      var c = string.charAt(i);
+      if (!Character.isWhitespace(c)) {
+        sb.append(c);
+      }
+    }
+    return sb.toString();
+  }
+}