Proposal to augment CD/faq/#verify
Hi,
during a lengthy thread on debian-user
https://lists.debian.org/debian-user/2024/08/msg00935.html
it became apparent, that the instructions on
https://www.debian.org/CD/faq/#verify
show some gaps in respect to tangible examples, especially for USB sticks.
- The headline mentions downloaded ISO images and optical media,
but not USB keys.
- The text points to the authenticity verification page
https://www.debian.org/CD/verify
which gives no tangible example how to verify *SUMS files by *SUMS.sign.
Quite a lot of experience is needed to convert the instructions to
actual program runs.
- The only example how to obtain SHA256 or SHA512 checksums is way down
in the text and shows "<" ">" brackets without explaining that these are
placeholders which must not appear in the actual command.
(I did not try what strange file would possibly emerge by redirection.)
- There is no example how to compare these long strings with the ones
listed in the *SUMS files.
- The second example for script check_debian_iso talks only of optical
media but not of USB sticks.
- There is no mentioning of verification failure due to USB stick groping
by MS-Windows or Lenovo BIOS, as discussed in bug 1056998 (which could
be closed, btw).
- My script
https://people.debian.org/~danchev/debian-iso/check_debian_iso
is advertised but no instruction for its verification is given.
The available signatures at
https://people.debian.org/~danchev/debian-iso/
are not by Debian-CD but rather by (inactive) DD George Danchev and by
me as developer of GNU xorriso.
That's insufficient for an instruction page about getting high trust
in the authenticity of downloaded and copied Debian ISOs.
So i propose:
- Copy
https://people.debian.org/~danchev/debian-iso/check_debian_iso
to an official Debian-CD location and (after verifying the existing
signatures) sign it by a Debian-CD key.
Show an example how to verify this signature after downloading the
script.
- Augment
https://www.debian.org/CD/faq/#verify
by tangible examples without placeholder characters which could cause
confusion with users who have few experience with the shell.
- Add a section about using the file /md5sum.txt of the ISO to get more
information about the alteration of the ISO if verification of a
USB stick fails due to third-party FAT filesystem groping.
------------------------------------------------------------------------
Proposal for new content of https://www.debian.org/CD/faq/#verify and
a new section about inspecting USB sticks which did not pass the check.
(Note that i know sha512sum option --ignore-missing. But old Debian
systems like Jessie do not know it.):
------------------------------------------------------------------------
How can I verify the downloaded ISO images and written media?
The checksum files SHA256SUMS and SHA512SUMS in the directories
with the ISO images can be verified by help of the PGP signature
files SHA256SUMS.sign and SHA512SUMS.sign by e.g.
$ gpg --keyserver keyring.debian.org --verify SHA512SUMS.sign SHA512SUMS
In case of successful verification this program run must report
essentially:
gpg: Good signature from "Debian CD signing key <debian-cd@lists.debian.org>"
...
Primary key fingerprint: DF9B 9C49 EAA9 2984 3258 9D76 DA87 E80D 6294 BE9B
The key title and the key fingerprint must match one of the pairs
"Key fingerprint =" and "uid" as listed on https://www.debian.org/CD/verify .
After this cryptographical verification of the checksum files, we can
use them to check that:
* Checksums of the downloaded ISO image files match those found in the
checksum files. Computing the checksum of the ISO image files is
performed by tools such as "sha512sum" and "sha256sum". E.g.:
$ grep ' debian-12.7.0-amd64-netinst.iso$' SHA512SUMS | sha512sum -c -
debian-12.7.0-amd64-netinst.iso: OK
* Checksums of already written optical media or USB keys match those found
in the checksum files if you curb the data stream from the medium to
the size of the ISO image.
This is necessary because nearly all media would return more bytes
after the end of the written ISO image. The checksums will only match
if the number of bytes is exactly the same as in the image.
There are several ways to achieve this exactness:
* The "isosize" program can be used to find out the appropriate amount
of bytes to be read from the media. It shows the "sector count" and the
"sector size" of the ISO filesystem on the medium. The latter is not
necessarily the storage block size of the medium, but always 2048.
Optical media are presented by GNU/Linux as /dev/srN, USB keys as
/dev/sdX. If the ISO is on a USB key presented as /dev/sdc:
$ /sbin/isosize -x /dev/sdc
sector count: 323072, sector size: 2048
If the ISO is on a CD, DVD or BD presented as /dev/sr0:
$ /sbin/isosize -x /dev/sr0
sector count: 323072, sector size: 2048
* Then "sector count" and "sector size" are passed to "dd" to read the
appropriate amount of bytes from the medium. The byte stream is then
piped to the appropriate checksum tool "sha512sum" or "sha256sum"
and memorized in a shell variable:
$ computed=$(dd if=/dev/sdc count=323072 bs=2048 | sha512sum | awk '{print $1}')
* The computed checksum is to be compared against the corresponding
checksum found in the appropriate checksum file SHA512SUMS or
SHA256SUMS:
$ recorded=$(grep ' debian-12.7.0-amd64-netinst.iso$' SHA512SUMS | awk '{print $1}')
$ test "$computed" = "$recorded" && echo "OK. MATCH."
OK. MATCH.
If the latter command puts out nothing instead of "OK. MATCH.", then the
verification check has failed and the ISO filesystem on the medium was
altered.
There are harmless reasons for this failure but also dangerous ones.
See the next section for an attempt to find altered files in the ISO.
This three-step procedure for media and also the two-step procedure for
image files may each be replaced by a run of the script
https://people.debian.org/~danchev/debian-iso/check_debian_iso .
* Download the script and give yourself x-permission:
$ wget https://people.debian.org/~danchev/debian-iso/check_debian_iso
...
2024-09-03 09:24:57 (144 MB/s) - ‘check_debian_iso’ saved [5373/5373]
$ chmod u+x ./check_debian_iso
* ISO image file verification is done by:
$ ./check_debian_iso SHA512SUMS debian-12.7.0-amd64-netinst.iso
* Media verification is done by:
$ ./check_debian_iso SHA512SUMS debian-12.7.0-amd64-netinst.iso /dev/sdc
or
$ ./check_debian_iso SHA512SUMS debian-12.7.0-amd64-netinst.iso /dev/sr0
The ISO image itself is not needed for these two runs with media.
Only its name is needed for looking it up in the checksum file.
The last output line of the ./check_debian_iso runs must then be like
Ok: '/dev/sdc' matches 'debian-12.7.0-amd64-netinst.iso' in 'SHA512SUMS'
A mismatch would yield
MISMATCH: '/dev/sdc' checksum differs from 'debian-12.7.0-amd64-netinst.iso' in 'SHA512SUMS'
If you are curious about the script's options, run
$ ./check_debian_iso -help
(The mentioned checksum files MD5SUMS and SHA1SUMS are not offered any
more, because these checksums are meanwhile deemed insufficient as
protection against malicious changes.)
>>> TODO: Move check_debian_iso to an official Debian location and sign
it by a Debian CD signing key. Then describe its verification.
(Currently it is signed by a key of George Danchev and by the
key of GNU xorriso by Thomas Schmitt.)
------------------------------------------------------------------------
New section. (Note that i know about the opportinity to run cdrom-checker.
But i deem it unwise to boot a possibly manipulated ISO just for
inspection.):
------------------------------------------------------------------------
How to find the altered files in case of no match
If the verification attempt yields a non-matching checksum although
you are quite sure that you got an original Debian ISO, it is possible
to look for files in the ISO which got hit by the alteration. This works
only if the alteration does not hamper mountability of the ISO filesystem.
Mount the damaged ISO with a mountpoint of your choice
$ path_to_image_or_usb_device=/dev/sdc
$ mountpoint=/mnt/iso
$ sudo mount "$path_to_image_or_usb_device" "$mountpoint"
Let program "md5sum" verify the files listed in "$mountpoint"/md5sum.txt
$ cd "$mountpoint"
$ md5sum -c ./md5sum.txt | grep ': FAILED$'
./EFI/debian/grub.cfg: FAILED
md5sum: WARNING: 1 computed checksum did NOT match
The altered file in this example is the image file which serves as
EFI System Partition when the ISO is presented to EFI on a USB key.
It often gets altered by proprietary software when you plug the USB key
into a running MS-Windows system. Normally this alteration is harmless and
just indicates that some small files were added to the FAT filesystem in
the system partition image. But such alteration of course weakens the
credibility of your download and copy efforts.
As noted in the previous section, MD5 is not a cryptographically secure
checksum any more. But it still is a good check against non-malicious
alterations.
------------------------------------------------------------------------
Have a nice day :)
Thomas
Reply to: