Downloading software is often treated as the end of a trust decision: the file came from the expected page, so the next step is to run it. That shortcut is risky. A release archive, installer, container image, or build tool can be corrupted in transit or storage, replaced at a distribution point, or fetched from an unexpected source while keeping a plausible filename.

Running the wrong bytes can turn a distribution failure into code execution inside a developer workstation, build system, or production environment. The defensive goal is therefore not merely to obtain an artifact. It is to establish that the bytes you received are the bytes an accepted publisher intended you to use.

This article explains the mental model behind artifact verification, the different guarantees provided by checksums and digital signatures, where the trusted verification information must come from, and how to build verification into a delivery process without assuming that one integrity check solves every supply-chain problem.

Treat downloaded bytes as a candidate, not proof

A filename is a label. A URL is a location. Neither proves the identity of the bytes that arrived.

Suppose a build job expects this release:

widget-builder-3.4.1.tar.gz

The job downloads a file with exactly that name. It now knows that it received some bytes under the expected label. It does not yet know whether those bytes match the release that the project intended to distribute.

Artifact verification adds a separate decision:

expected release
      |
trusted verification information
      |
received bytes -> verify -> accept or reject

The important separation is between the artifact and the evidence used to verify it. If an attacker can replace both through the same compromised path, comparing one with the other may provide little protection.

That leads to the central rule: verification is useful only when the verification evidence is anchored in something you already trust.

Start with the threat model

Artifact verification is mainly intended to reduce the risk that different bytes are substituted for the artifact you meant to consume. Relevant failure conditions include accidental corruption, a compromised mirror or storage location, and an attacker who can alter an artifact somewhere in the distribution path.

The control does not establish that the publisher’s source code is harmless. It does not prove that the publisher’s build environment was uncompromised. It also does not make a legitimately signed vulnerable release non-vulnerable.

Those are different supply-chain questions.

For this article, assume that you have a trustworthy way to obtain either an expected cryptographic digest or authenticated release metadata, and that the cryptographic algorithms and verification implementation are suitable for the system. Under those assumptions, verification can tell you whether the received artifact matches the authenticated expectation.

Understand what a cryptographic digest tells you

A cryptographic hash function maps arbitrary input bytes to a fixed-size value called a digest. Changing the input normally produces a different digest. Modern artifact workflows commonly use a collision-resistant hash such as SHA-256 or a stronger algorithm supported by the relevant ecosystem.

A simplified verification flow looks like this:

expected digest: 8f...21
received file:   widget-builder-3.4.1.tar.gz

hash(received file) -> 8f...21
compare             -> match

If the computed digest differs from the trusted expected digest, reject the artifact. The bytes are not the artifact represented by that digest.

This is useful for detecting corruption and substitution, but a digest has an important limitation: the hash does not authenticate itself.

Imagine a download page publishes both an archive and its SHA-256 value. If an attacker controls that page and can replace the archive, the attacker may also be able to replace the displayed digest with the digest of the substituted file. The comparison will succeed because both pieces of information came through the compromised trust boundary.

So the useful question is not simply:

Does the file match this checksum?

It is:

Why do I trust this expected checksum?

A checksum obtained through an independently trusted release manifest, pinned build metadata, or another authenticated channel can be meaningful evidence. A checksum copied from the same untrusted location as the artifact may provide corruption detection without providing strong protection against a malicious substitution at that location.

Use signatures when you need publisher authentication

A digital signature can bind release data to a signing key. In a typical public-key signature system, the publisher holds a private signing key and consumers verify signatures using the corresponding public key or a trust mechanism that ultimately identifies an accepted signer.

The mental model is:

publisher private key
        |
   signs release data
        |
artifact or manifest + signature
        |
trusted signer identity -> verify -> accept or reject

Successful signature verification establishes more than an unauthenticated checksum comparison. Under the assumptions of the signature scheme and key trust model, it shows that the signed data was produced by a holder of the relevant private key and has not been altered without invalidating the signature.

But the key identity is part of the security decision. A valid signature from an unknown or untrusted key does not prove that the artifact came from the publisher you intended. Verification therefore needs two checks:

  1. Is the signature cryptographically valid for the data?
  2. Is the signer one that this system is configured to trust for this artifact?

Skipping the second check reduces signature verification to proving that someone with a key signed the data.

Different ecosystems answer signer identity differently. Some use long-lived public keys, some use repository or package metadata, and some use identity-backed signing systems with transparency records. The implementation details vary, but the underlying decision remains the same: authenticate the release expectation before trusting the artifact.

Verify the right bytes before they cross the execution boundary

Verification is most useful when it happens before the artifact can influence a trusted system.

Consider a build pipeline that downloads a compiler helper and then executes it:

download
unpack
run
verify

The verification step is too late. Unpacking can itself invoke complex parsers, and execution has already crossed the critical boundary.

A safer sequence is:

download to temporary location
verify expected identity and integrity
reject on verification failure
only then unpack or execute

The exact boundary depends on the artifact. For a plain archive, verification normally applies to the archive bytes before extraction. For a container image, a platform may verify signed image metadata or an immutable digest before deployment. For packages managed by an ecosystem, the package manager may already verify repository metadata and package integrity as part of installation.

Do not add a parallel homemade mechanism merely because verification sounds useful. First identify what the ecosystem already authenticates, what trust root it uses, and which gap you are trying to close.

Make verification deterministic in automated builds

Manual verification can help a person installing an occasional tool, but repeated builds need a reproducible trust decision.

A build should not silently accept whatever digest or signing key happens to be advertised at download time. The expected identity should come from controlled configuration or authenticated metadata whose update path is itself reviewed.

A simplified policy might be:

artifact: widget-builder-3.4.1.tar.gz
expected_sha256: <reviewed digest>

on build:
    download artifact
    calculate sha256
    if calculated != expected_sha256:
        stop
    continue build

The placeholder above is deliberately not a real digest; production configuration must contain the exact reviewed value for the intended artifact.

This pattern makes a version update an explicit trust change. Moving from 3.4.1 to 3.4.2 requires updating the expected verification data rather than automatically trusting new bytes because they appear under a newer version number.

Where an ecosystem provides authenticated lockfiles, signed repository metadata, immutable image digests, or equivalent mechanisms, prefer those established controls over inventing a custom file format. The goal is not to make every team maintain its own cryptographic protocol. The goal is to make artifact identity explicit and verifiable.

Keep the artifact and its evidence from sharing one failure path

A common implementation mistake is to fetch an artifact and its checksum from adjacent unauthenticated locations and call the result verified.

For example:

mirror/releases/tool.tar.gz
mirror/releases/tool.tar.gz.sha256

If the mirror is only a cache and the expected digest was already recorded in trusted build configuration, the mirror can be treated as an untrusted source of bytes: a modified file will fail the local comparison.

If the build fetches both the file and the expected digest from that same mirror at runtime, compromise of the mirror may let an attacker change both. The two-file arrangement then provides much weaker assurance against malicious replacement.

The defensive design is to separate where bytes are obtained from why those bytes are trusted. This separation lets organisations use mirrors and caches for availability without automatically giving those systems authority to redefine an accepted release.

Plan for verification failure instead of bypassing it

Integrity controls often fail at inconvenient times: a publisher rotates a signing key, a release is republished, metadata expires, or a mirror serves incomplete data. The dangerous operational response is a bypass such as “skip verification for this build.”

A verification failure means the system cannot establish the artifact identity under its current trust rules. Treat that as a reason to stop consumption and investigate, not as evidence that the artifact is malicious and not as permission to continue.

A practical recovery path should answer:

  • how a new signing key or expected digest becomes trusted;
  • who reviews that change for sensitive build paths;
  • how an emergency update is recorded;
  • how old trust material is retired without accepting arbitrary replacements.

For low-impact internal tooling, peer review of a pinned digest update may be sufficient. For production release infrastructure or highly privileged build tools, stronger separation of duties and authenticated signing workflows can be justified because a substituted artifact would have a larger impact.

Availability matters, but weakening verification during an outage changes the trust model exactly when operators are under pressure. Design the update and recovery path before that pressure exists.

Avoid confusing integrity with provenance or safety

Three questions are easy to merge accidentally:

Integrity:  Are these the expected bytes?
Provenance: Where did these bytes come from, and how were they produced?
Safety:     Should we run these bytes in this environment?

A trusted digest can answer the first question if the digest itself is authentic. A signature can also authenticate signed release information according to its key or identity model. Neither automatically proves how the software was built or whether its behavior is acceptable.

This distinction matters after a publisher compromise. If an attacker gains legitimate release authority, malicious bytes may be correctly signed. Signature verification can still work exactly as designed while the broader software supply chain has failed.

That residual risk calls for complementary controls such as dependency review, protected build and release systems, least privilege for build jobs, vulnerability management, and monitoring. Artifact verification remains useful because it removes one class of ambiguity: unapproved byte substitution after the trusted release expectation has been established.

Test the control as a security boundary

A verification mechanism should be tested for failure, not only for the normal download path.

Use harmless test artifacts and confirm that the consumer:

  • accepts the intended artifact when the expected evidence is valid;
  • rejects a file after even a small byte change;
  • rejects missing or malformed verification data rather than continuing;
  • rejects signatures from keys or identities that are not authorised for that artifact;
  • does not unpack, execute, install, or deploy the artifact before verification succeeds;
  • records enough information to diagnose a failure without logging secret signing material.

Also test the trust-update path. A control that operators cannot update safely will eventually encourage bypasses.

The desired property is simple to state: no artifact crosses the relevant execution or deployment boundary unless the system can establish its identity using trusted verification information.

Choose the simplest control that matches the risk

Not every artifact needs an elaborate signing infrastructure.

If a small internal build downloads a fixed public tool and the team can securely review and pin its cryptographic digest, digest verification may provide the needed substitution protection. It is simple, deterministic, and easy to test.

If artifacts are released frequently, distributed broadly, or produced by multiple authorised publishers, authenticated metadata or signatures can make trust updates more manageable. Higher-impact environments may also need stronger key protection, signer separation, transparency, or provenance controls.

The choice should follow the threat model. Ask who could alter the artifact, who is authorised to approve a release, how consumers learn that identity, and what happens when trust material changes.

Conclusion

Downloading an artifact gives you bytes, not proof that they are the bytes you intended to trust. Verification closes that gap by comparing the received artifact with authenticated expectations before the artifact can execute or be deployed.

Use cryptographic digests when a trusted expected digest is sufficient. Use signatures or authenticated ecosystem metadata when publisher authentication and scalable release updates matter. In either case, protect the trust path for the verification evidence, reject failures rather than bypassing them, and remember the boundary of the guarantee: artifact verification reduces substitution risk, but it does not prove that legitimately released software is harmless.

Cybersecurity Software Supply Chain Integrity Artifact Verification