The idea
A hash turns any file into a short fingerprint: the same bytes always give the same digest, and one changed byte gives a completely different one. Maren runs the download mirror for Tollgate Software, and a user has reported that the installer "looks wrong".
You'll fingerprint the genuine build, watch a single changed character rewrite the whole digest, then find the catch: on a mirror the attacker controls, the swapped file and its checksum both pass the official check. A keyed hash closes that gap, because producing the right one needs a secret key the attacker doesn't have.
Steps
-
A fingerprint for a file
A cryptographic hash reads every byte of a file and boils it down to a short, fixed-length fingerprint. SHA-256 always gives 64 hexadecimal characters, whether the file is one line or a gigabyte. The same bytes always give the same digest, the function can't be run backwards, and no one knows how to find two different files that share a digest: that last property is called collision resistance.
Those three properties are what checking a download rests on. If you know the digest a file is supposed to have, you recompute it yourself and compare.
Maren keeps the genuine installer at
/srv/tollgate-setup. Fingerprint it withsha256sum.host:~# sha256sum /srv/tollgate-setup
-
Change one byte, change the whole fingerprint
Maren rebuilt the installer for a point release: the version string went from
1.0.0to1.0.1, and nothing else changed. A single character of the file is different.A good hash spreads every input bit across the whole output, so flipping one bit flips about half the output bits, with no pattern. That is the "avalanche" effect, and it's why near-identical files get digests that look unrelated. Collision resistance is why any change at all, a typo or a quietly added backdoor, gives a different digest.
Fingerprint the rebuilt file and compare it to the one above.
host:~# sha256sum /srv/tollgate-setup-1.0.1
-
The checksum that lies
That user was right to worry: overnight, Maren's mirror was broken into. The genuine installer was swapped for a trojaned build, and whoever did it also rewrote the
SHA256SUMSfile sitting right beside it. Run the official check.sha256sum -creads a sums file, recomputes each listed file's digest, and printsOKorFAILED. It's a good check against an accident: a corrupted download, a transfer cut short, a bit flipped in transit.It rests on one assumption, though: that the
SHA256SUMSyou trust came from somewhere the attacker couldn't reach. On a mirror the attacker controls, that assumption is gone.(Swapping a file on a download server you haven't been authorised in writing to test is a crime. Here the mirror is Maren's own, and the swap is the move you're learning to catch.)
host:~# sha256sum -c /srv/SHA256SUMS
-
A tag only the keyholder can make
Tollgate's own deploy server pulls each release from that same mirror, so it faces the attack you saw in the last step. It doesn't trust a bare digest: the build pipeline and the deploy server share a secret key, which never goes on the mirror.
For each artifact, the pipeline computes an HMAC, the standard keyed hash: a SHA-256 with the key mixed in. Its output is called a tag, and it sits on the mirror beside the artifact. The deploy server recomputes the tag with its own copy of the key and accepts the artifact only if the two agree.
Read the tag the mirror serves for
/srv/release.tar, then recompute it the way the deploy server does.host:~# cat /srv/release.tar.hmac host:~# openssl dgst -sha256 -hmac 'tollgate-build-hmac-key' /srv/release.tar
-
The tag the attacker cannot forge
The attacker tries the same trick on this release: they tamper with
/srv/release.tarand rewrite the tag beside it, as they rewroteSHA256SUMS. They know the scheme is HMAC-SHA-256 but not the key, so the best they can do is compute a tag with a guessed one.Read the tag the mirror serves now, then recompute it with the real key, as the deploy server does.
host:~# cat /srv/release.tar.hmac host:~# openssl dgst -sha256 -hmac 'tollgate-build-hmac-key' /srv/release.tar
Run these steps on real machines