skip to content

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…