skip to content

distributionSha256Sum Integrity

4 roadmaps5 questions

Pinning distributionSha256Sum so the wrapper refuses a tampered distribution download. A concrete supply-chain measure interviewers like because it costs a single line.

on this pageshow

explore

questions

5

What is the distributionSha256Sum property in gradle-wrapper.properties, and what does it protect against?

level: juniorimportance: must knowfreq 45%

answer

  1. SHA-256 of the distribution ZIP
  2. line in gradle-wrapper.properties
  3. verified on download, fail-closed
  4. supply-chain / tampered mirror defense
  5. complements HTTPS, not replaces it

basics

~10 s

It's a SHA-256 checksum of the Gradle distribution ZIP, stored in gradle-wrapper.properties. The wrapper verifies the downloaded distribution against it and aborts if they don't match, protecting against a tampered or corrupted download.

solid answer

~40 s

`distributionSha256Sum` is an optional line in `gradle-wrapper.properties` holding the expected SHA-256 hash of the Gradle distribution archive named by `distributionUrl`. When the wrapper downloads that archive, it computes the SHA-256 of the bytes it received and compares it to this pinned value. On a mismatch the build fails before the distribution is unpacked or executed — so no untrusted Gradle code runs. This defends against a corrupted download, a compromised mirror/CDN, or a man-in-the-middle who swaps the ZIP. Without it, the wrapper trusts whatever the URL serves. It complements (but is separate from) verifying the wrapper JAR itself; this property is specifically about the downloaded *distribution* archive.

code

toml · 7 lines
toml
# gradle/wrapper/gradle-wrapper.properties
distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-8.7-bin.zip
distributionSha256Sum=544c35d6bd849ae8a5ed0bcea39ba677dc40f49df7d1835561582da2009b961d
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

go deeper

for a junior

Know it's a SHA-256 of the Gradle distribution ZIP in gradle-wrapper.properties and that a mismatch fails the build.

for a middle

Explain it's verified at download time, fails closed before execution, and why it adds value beyond HTTPS.

for a senior

Frame it as supply-chain defense-in-depth, distinguish it from wrapper-JAR verification, and know where the official sum is published.

for a principal

Position it within a software-supply-chain policy: enforce pinning org-wide, fail closed, and treat the distribution as untrusted-until-verified code.

## What the wrapper does The Gradle Wrapper is a small script + JAR checked into your repo. On first use it reads `gradle/wrapper/gradle-wrapper.properties`, downloads the Gradle distribution named by `distributionUrl` (e.g. `gradle-8.7-bin.zip`), unpacks it under `~/.gradle/wrapper/dists/`, and then executes that Gradle. Because the wrapper *runs* the downloaded code, the integrity of that download is a supply-chain concern. ## The property `distributionSha256Sum` is an optional key in `gradle-wrapper.properties`: ```properties distributionUrl=https\://services.gradle.org/distributions/gradle-8.7-bin.zip distributionSha256Sum=544c35d6bd849ae8a5ed0bcea39ba677dc40f49df7d1835561582da2009b961d ``` When present, after downloading the archive the wrapper computes its SHA-256 and compares it to this value. **Mismatch ⇒ the build fails immediately**, before unpacking or running anything. So an attacker who can serve a different ZIP (compromised mirror, poisoned cache, MITM on a non-HTTPS or intercepted connection) cannot get their code executed — the hash won't match. ## Why HTTPS isn't enough HTTPS protects bytes *in transit* from the server you connected to. The checksum additionally protects against a compromised or malicious server/mirror, a poisoned CDN edge, or an internal proxy that rewrites artifacts. It's defense-in-depth and pins the *exact* expected artifact. ## Where the expected value comes from Gradle publishes the SHA-256 for every distribution on its download/checksum pages. You paste that official value. The safest way to *write* it is not to copy by hand but to let the `wrapper` task pin it (covered by the `--gradle-distribution-sha256-sum` flow), but the property itself — its meaning and the verify-on-download behavior — is what matters here. ## Failure behavior If the downloaded archive's hash differs, Gradle prints an error like `Verification of Gradle distribution failed!` showing the expected vs actual sum and stops. This is fail-closed: no Gradle from that download executes. ## Scope note This verifies the *distribution archive*. The wrapper JAR (`gradle-wrapper.jar`) committed in your repo is a separate artifact verified by other means; don't conflate the two.

  • What happens if the property is present but the downloaded archive's hash doesn't match?
    The wrapper fails the build immediately with a 'Verification of Gradle distribution failed!' error showing expected vs actual sum, and never unpacks or executes the distribution.
  • Does distributionSha256Sum verify the gradle-wrapper.jar?
    No. It only verifies the downloaded distribution archive named by distributionUrl. The committed wrapper JAR is a separate artifact verified separately.

saying these in an interview costs you the question

  • Claiming HTTPS makes the checksum redundant — it doesn't cover a compromised mirror/CDN.
  • Saying it verifies the wrapper JAR or the build scripts — it only covers the distribution archive.
  • Thinking it's hashed locally as defense against runtime tampering — it's verified once, at download time.

context

resolving links…

open as a page

How do you pin the distribution checksum using the wrapper task instead of editing gradle-wrapper.properties by hand?

level: middleimportance: must knowfreq 40%

basics

~10 s

Run the wrapper task with --gradle-distribution-sha256-sum and the official checksum, e.g. ./gradlew wrapper --gradle-version 8.7 --gradle-distribution-sha256-sum <sum>. Gradle writes distributionSha256Sum into gradle-wrapper.properties for you.

open as a page

A teammate reports 'Verification of Gradle distribution failed!' after pulling your branch. How do you diagnose and resolve it?

level: middleimportance: should knowfreq 28%

basics

~20 s

It means the downloaded distribution's SHA-256 didn't match distributionSha256Sum. Check whether distributionUrl and the pinned sum are consistent (right version/type), clear the cached partial download, and re-pin via the wrapper task if the sum was wrong.

open as a page

Where do you obtain the correct SHA-256 to pin, and how do you verify you're pinning a trustworthy value?

level: middleimportance: should knowfreq 30%

basics

~20 s

Use the official SHA-256 that Gradle publishes for each distribution on its checksum/download pages. Copy the value for the exact version and archive type you're using; don't compute it from a download you don't trust.

open as a page

How would you enforce distribution-checksum pinning across many repositories in an organization, and what are the trade-offs?

level: seniorimportance: should knowfreq 18%

basics

~10 s

Require distributionSha256Sum in every gradle-wrapper.properties, enforce it with a CI lint/check that fails when it's missing or mismatched, and standardize upgrades through the wrapper task so the URL and sum are always pinned together.

open as a page