What is checksum verification in Gradle's dependency verification, and what problem does it solve?
answer
- re-hash on every resolution
- verification-metadata.xml component/artifact entries
- md5/sha1/sha256/sha512 elements
- mismatch -> build fails
- integrity, not authorship
basics
~10 sGradle records an expected hash (e.g. sha256) for each downloaded artifact in verification-metadata.xml. On every build it re-hashes the file and fails if it differs, proving the artifact wasn't tampered with or swapped.
solid answer
~40 sChecksum verification is part of Gradle's dependency-verification feature. When enabled, Gradle expects a `verification-metadata.xml` file under `gradle/` that lists, per artifact (jar, pom, module metadata), one or more cryptographic checksums (`md5`, `sha1`, `sha256`, `sha512`). On resolution Gradle computes the hash of each file it pulls from a repository and compares it to the recorded value. A mismatch — or a missing entry, depending on configuration — fails the build. This protects against a compromised or hijacked repository serving a malicious artifact, accidental corruption, or a cache-poisoning man-in-the-middle. It's purely integrity verification ("is this the exact bytes I trust?"), distinct from PGP signature verification which proves *who* published it. Checksums are simple, fast, and don't require any keyring infrastructure.
code
xml · 8 lines<component group="org.apache.commons" name="commons-lang3" version="3.14.0">
<artifact name="commons-lang3-3.14.0.jar">
<sha256 value="d919d904486c037f8d193412da0c92e22a9fa24230b9d67a57855c5c31c7e94e"/>
</artifact>
<artifact name="commons-lang3-3.14.0.pom">
<sha256 value="8b3e9..."/>
</artifact>
</component>go deeper
Define it: Gradle stores an expected hash per artifact and fails the build if the downloaded file's hash differs. Name sha256 and the verification-metadata.xml file.
Explain it verifies every downloaded file (jar/pom/.module), the algorithm choices, and that a missing or mismatched entry fails resolution.
Frame it as supply-chain integrity, contrast with signature verification, and note the bootstrapping trust-on-first-use caveat.
Position checksum verification within an org-wide artifact-integrity policy: who reviews the generated metadata, how it interacts with an internal proxy/mirror, and when integrity alone is insufficient versus signatures.
## What checksum verification is Gradle's **dependency verification** feature lets you pin the exact bytes of every artifact your build consumes. Checksum verification is one of its two pillars (the other being PGP signatures). It works by storing, for each artifact, a cryptographic hash that Gradle re-computes and compares on every resolution. The data lives in `gradle/verification-metadata.xml`. The presence of this file is what *enables* verification — there is no separate on/off flag in build scripts. A component block looks like: ```xml <component group="com.google.guava" name="guava" version="33.0.0-jre"> <artifact name="guava-33.0.0-jre.jar"> <sha256 value="a42edc9c..." origin="Generated by Gradle"/> </artifact> <artifact name="guava-33.0.0-jre.module"> <sha256 value="7b9f..."/> </artifact> </component> ``` ## What gets verified Gradle verifies **every file** it downloads for a dependency, not just the main jar: the `.jar`, the `.pom`, the Gradle Module Metadata (`.module`), sources/javadoc jars, and even plugin marker artifacts. Each `<artifact>` element carries one or more checksum children. ## The algorithms Valid element names are `<md5>`, `<sha1>`, `<sha256>`, `<sha512>`. `md5` and `sha1` are considered cryptographically broken (collisions are feasible) and exist mainly because some old repos only publish those — Gradle warns if you rely on them alone. **`sha256` is the recommended default**; `sha512` is available when you want maximum strength. ## How the check runs 1. Gradle resolves a configuration and needs file X from a repository. 2. It downloads X (or reads it from the cache) and computes the configured hashes. 3. It looks up the matching `<artifact>` in `verification-metadata.xml`. 4. If a recorded checksum matches → pass. If it differs → **the build fails immediately** with a verification report. If an artifact is *missing* from the metadata, behavior depends on the `verify-metadata`/strict configuration: by default a missing entry is also a failure, which is the point — an attacker can't sneak in a new transitive dependency unnoticed. ## Bootstrapping You don't hand-write hashes. Run: ```bash ./gradlew --write-verification-metadata sha256 help ``` Gradle resolves the requested tasks, downloads everything, and writes the computed `sha256` values into the file with `origin="Generated by Gradle"`. You then **review and commit** that file. From then on any tampered or substituted artifact produces a different hash and breaks the build. ## Why it matters A public repository (or a mirror/proxy in front of it) is part of your supply chain. If it's compromised and serves a backdoored `log4j.jar` with the same coordinates, only an integrity check catches it. Checksum verification gives you that with zero key-management overhead — its weakness is bootstrapping trust (you trust whatever bytes you first hashed), which is exactly why teams review the generated file and combine it with signature verification for stronger provenance.
- Does checksum verification tell you who published an artifact?No. A checksum only proves the bytes match what you recorded (integrity). Proving the publisher's identity requires PGP signature verification, which checks a signature against a trusted key.
- Which files of a dependency get verified — just the jar?All downloaded files: the jar, pom, Gradle Module Metadata (.module), and sources/javadoc/plugin-marker artifacts. Each is a separate <artifact> entry with its own checksum.
Like a tamper-evident seal on a package: you recorded the seal's serial number once; if the number on delivery differs, you refuse the box — even if the label looks right.
saying these in an interview costs you the question
- Saying checksums verify the publisher's identity — that's signatures, not hashes.
- Thinking only the main jar is checked (the pom and .module are also verified).
- Claiming you must type the hashes by hand instead of generating them.