From aadfd0c155cbdfbaf62268b7c83a67a9d9efcf67 Mon Sep 17 00:00:00 2001 From: Adam Kaplan Date: Thu, 21 May 2026 22:34:58 -0500 Subject: [PATCH] Doc: Trusted Checksums Summary File Procedure Document the procedure to save Trusted Checksum summary files to version control. This procedure utilizes the `.mvn/config` file for consistent invocation and the `${session.rootDirectory}` variable, which is only available in Maven 3.9.x. The configuration was taken from an example "locked down" repository provided by @cstamas. [1] Unfortunately, saving Trusted Checksum summary files to version control can cause dependency management tools like Renovate and GitHub Dependabot to break builds. It is my hope that with improved documentation, the dependency management tool ecosystem will be able to appropriately update these trusted checksum files if present. [1] https://github.com/ipfs-shipyard/java-ipfs-http-client Signed-off-by: Adam Kaplan --- src/site/markdown/expected-checksums.md | 38 +++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/src/site/markdown/expected-checksums.md b/src/site/markdown/expected-checksums.md index 6038d8c12..adad43497 100644 --- a/src/site/markdown/expected-checksums.md +++ b/src/site/markdown/expected-checksums.md @@ -181,6 +181,34 @@ and the same tools can be also used to "batch verify" the enlisted artifacts in Each summary file contains information for single checksum algorithm, represented as summary file extension. +If you are using Maven 3.9.x, use the following procedure to save the summary checksum file alongside your project code: + +1. Add the following command line flags to your `.mvn/config` file: + + ``` + --strict-checksums + -Daether.checksums.algorithms=SHA-512,SHA-1,MD5 + -Daether.trustedChecksumsSource.summaryFile=true + -Daether.trustedChecksumsSource.summaryFile.basedir=${session.rootDirectory}/.mvn/checksums/ + -Daether.artifactResolver.postProcessor.trustedChecksums=true + -Daether.artifactResolver.postProcessor.trustedChecksums.checksumAlgorithms=SHA-512 + -Daether.artifactResolver.postProcessor.trustedChecksums.failIfMissing=true + ``` + +2. Run a build with trusted checksum recording enabled: + + ```sh + mvn clean install -Daether.artifactResolver.postProcessor.trustedChecksums.record=true + ``` + + This will generate one or more checksum files (one for each source Maven repository) with the `.sha512` extension. + +3. Verify that the build succeeds with trusted checksum recording disabled: + + ```sh + mvn clean install + ``` + ### Sparse Directory Trusted Checksums Source This source mimics Maven local repository layout, and stores checksums in similar layout @@ -189,3 +217,13 @@ as Maven local repository stores checksums in local repository. Here, just like Maven local repository, the sparse directory can contain multiple algorithm checksums, as they are coded in checksum file path (the extension). +### Notes On Using Trusted Checksums + +- Use the `--strict-checksums` flag to fail a build if the expected checksums of downloaded + artifacts do not match. +- More than one checksum algorithm can be specified for the + `aether.artifactResolver.postProcessor.trustedChecksums.checksumAlgorithms` system property. The + listed checksums must be a subset of those specified by `aether.checksums.algorithms`. +- Most dependency management tools do not currently update trusted checksum files if they are + stored in version control alongside source code. We hope maintainers of these tools support + Maven trusted checksums in the near future.