skip to content

How does Maven verify artifact integrity with checksums, and what does running with -C (strict checksum policy) change?

level: middleimportance: should knowfreq 35%

answer

  1. .sha1/.md5 sidecar files
  2. policy: warn (default) vs fail
  3. -C / --strict-checksums = fail
  4. checksumPolicy per <releases>/<snapshots>
  5. integrity NOT authenticity

basics

~10 s

Every artifact has companion .sha1/.md5 checksum files. Maven downloads them and compares. By default a mismatch only warns; running mvn -C makes a mismatch a hard build failure.

solid answer

~40 s

When Maven downloads a JAR or POM it also fetches the matching checksum sidecar files (.sha1, .md5, and increasingly .sha256/.sha512). It recomputes the hash of the downloaded bytes and compares. The behavior on mismatch depends on the checksum policy: the default 'warn' logs a warning but proceeds, while 'fail' aborts the download. You set 'fail' globally on the CLI with -C / --strict-checksums, or per repository via <releases>/<snapshots> <checksumPolicy>fail</checksumPolicy>. Strict checksums catch corruption and crude tampering in transit or in a cache. Important limitation: checksums prove integrity against THAT published checksum, not authenticity — an attacker who controls the repository can publish a matching malicious artifact and checksum. So -C complements, but does not replace, PGP signature verification and locking to trusted sources.

code

bash · 3 lines
bash
# Fail the build on any checksum mismatch
mvn -C clean verify
# (equivalently: mvn --strict-checksums clean verify)

go deeper

for a junior

Knows artifacts have checksum files Maven can compare to detect corruption.

for a middle

Knows the warn-vs-fail policy and that -C makes mismatches fail; can set checksumPolicy per repo.

for a senior

Distinguishes integrity from authenticity and pairs checksums with signatures and source locking.

for a principal

Mandates -C in CI and drives a policy combining checksum + PGP + single trusted source across the org.

## What checksums are For every artifact (`foo-1.0.jar`, `foo-1.0.pom`) a repository also hosts small **checksum sidecar files** with the same name plus a hash extension: - `foo-1.0.jar.sha1` - `foo-1.0.jar.md5` - newer repos also publish `.sha256` / `.sha512` A checksum file contains the hex digest of the artifact's bytes. When Maven downloads the artifact it also downloads the checksum, recomputes the hash locally, and compares. ## Checksum policy The reaction to a mismatch (or missing checksum) is governed by the **checksum policy**, which has two values: - **`warn`** (default): log a warning, keep going. - **`fail`**: treat a mismatch as an error and refuse the artifact. ### Setting it on the command line ```bash # -C / --strict-checksums => policy = fail mvn -C clean verify # -c / --lax-checksums => policy = warn (the default) mvn -c clean verify ``` ### Setting it per repository ```xml <repository> <id>acme-virtual</id> <url>https://nexus.acme.internal/repository/maven-virtual/</url> <releases> <checksumPolicy>fail</checksumPolicy> </releases> <snapshots> <checksumPolicy>fail</checksumPolicy> </snapshots> </repository> ``` ## What -C protects against (and what it doesn't) **Protects against:** bit-rot/corruption during transfer, a partially written or truncated cache, and unsophisticated tampering where the attacker swapped the JAR but not the checksum. **Does NOT protect against:** an attacker who controls (or has write access to) the repository. They can publish a malicious JAR **and** a matching checksum; the hash will verify cleanly. Checksums establish **integrity** (the bytes match the published hash), not **authenticity** (the bytes came from a party you trust). That authenticity gap is exactly what **PGP signatures** (`maven-gpg-plugin`) and **source locking** (mirrors to trusted repos) close. Use all three together: lock the source, verify the signature, and enforce checksums. ## Practical notes - MD5/SHA-1 are cryptographically weak; rely on SHA-256/512 where the repo provides them, and treat checksums as integrity not security. - In CI, prefer enforcing `-C` so a corrupted mirror entry fails fast rather than producing a flaky build.

  • Does a passing checksum mean the artifact is safe?
    No. It only proves the bytes match the published hash. An attacker controlling the repo can publish a malicious JAR with a matching checksum. You also need signature verification and trusted sourcing.
  • What is the default checksum policy if you don't pass -C?
    'warn' — a mismatch logs a warning but the build continues, which is why explicit -C (fail) is recommended in CI.

saying these in an interview costs you the question

  • Claiming checksums verify authenticity or protect against a compromised repository.
  • Assuming -C is the default (it is not; warn is).
  • Relying solely on MD5/SHA-1, which are cryptographically broken.

context

resolving links…