How to verify the integrity of a downloaded image

All TurnKey Linux software appliance images have an accompanying .hash file (was labelled a .sig file in previous releases). This file contains the SHA256 and SHA512 checksum of the relevant image. It is also signed with the private component of our PGP release key.

Getting the .hash file

Using 14.2 Core ISO as an example, you can find the relevant .hash file by clicking the "Manifest & Sigs" link on the appliance page. I.e. in our case, we'd browse to the Core appliance page, click the "Manifest & Sigs" links, then download the file:

https://releases.turnkeylinux.org/turnkey-core/14.2-jessie-amd64/turnkey-core-14.2-jessie-amd64.iso.hash

The .hash files are also available direct from one of our mirrors, e.g. you will find both the ISO and the .hash file together via http://mirror.turnkeylinux.org/turnkeylinux/images/iso/

Note the ISO file and the .hash file should have almost identical names (with the exception of the .hash on the end of the .hash file). I.e. Core ISO and relevant .hash file filenames:

turnkey-core-14.2-jessie-amd64.iso
turnkey-core-14.2-jessie-amd64.iso.hash

The file itself contains instructions, but we'll cover the whole process here. The verification is essentially a 2 step process. First check the hash file was provided by us (i.e. confirm the signature). Then check the hash of the ISO file against what is published in the .hash file.

Verify the hash file

To verify the integrity of the downloaded hash file, you must first add the public component of the TurnKey Linux release key to your keychain.

For example, if you are using GPG you can download the key directly from TurnKey's Keybase.io profile:

$ curl https://keybase.io/turnkeylinux/pgp_keys.asc | gpg --import
$ gpg --list-keys --with-fingerprint release@turnkeylinux.com
  pub   2048R/A16EB94D 2008-08-15 [expires: 2023-08-12]
        Key fingerprint = 694C FF26 795A 29BA E07B  4EB5 85C2 5E95 A16E B94D
  uid   Turnkey Linux Release Key <release@turnkeylinux.com>

For extra points, you can confirm the key separately within you web browser by comparing the fingerprint displayed against what is shown on Keybase: https://keybase.io/turnkeylinux

Then verify that the .hash file is signed with our key.

$ gpg --verify turnkey-core-14.2-jessie-amd64.iso.hash
  gpg: Signature made using RSA key ID A16EB94D
  gpg: Good signature from "Turnkey Linux Release Key <release@turnkeylinux.com>"

Verify the checksum of the ISO against the hash file

Ensure that the ISO file and the .hash file are in the same directory. The quickest, easiest way is to use the relevant flavour of the shasum tool to automatically check the ISO against the checksums in the .hash file; like this:

$ sha256sum -c turnkey-core-14.2-jessie-amd64.iso.hash
  turnkey-core-14.2-jessie-amd64.iso: OK
  sha256sum: WARNING: 48 lines are improperly formatted

$ sha512sum -c turnkey-core-14.2-jessie-amd64.iso.hash
  turnkey-core-14.2-jessie-amd64.iso: OK
  sha512sum: WARNING: 48 lines are improperly formatted

Please note that you can safely ignore the warning regarding "improperly formatted lines". That's just because we also include instructions within the hash file (and obviously they aren't properly formatted checksums!). The important part is where it says "turnkey-core-14.2-jessie-amd64.iso: OK".

Alternatively, you can generate the checksum and manually compare that against the relevant checksum in the .hash file. E.g.:

$ sha256sum turnkey-core-14.2-jessie-amd64.iso
  171bb1c9fdba78830e7c5c0d084cf4b448ae564b041fff592f46a9306d51dbf7  turnkey-core-14.2-jessie-amd64.iso

$ sha512sum turnkey-core-14.2-jessie-amd64.iso
  20470be463dcb7f3b3a8a6ba4d8b25643775c8495547c75ba7c3ed545b4b0535892d84c40c987d00acf5eddbc49c9195556e750935456e9e538e5cccca7b3093  turnkey-core-14.2-jessie-amd64.iso

What to do if it fails?

If the first (signature validation) step fails, then there is a slim chance that the file has been corrupted. If you can open it in a Linux friendly text editor (i.e. NOT notepad or any word processing software) and read it clearly, then corruption is highly unlikely and something malicious is possible. If this occurs, please alerts us ASAP by posting on the forums ideally, or emailing to support@turnkeylinux.org.

If the second step (validating the ISO checksum) fails, then corruption is possible. I suggest that you copy the checksum that you got from your original ISO (so we can compare later), and download it again.

Repeat the second step again and hopefully it should now work. If not, compare the first ISO's checksum against the checksum generated from the new ISO. If they don't match (i.e. you now have 2 ISOs and a .hash file; neither of the ISO checksums match each other, or the hash in the .hash file) then it seems likely that there is something messing up your internet traffic and corrupting the image. You can try again, or perhaps try from a different mirror.

If the 2 ISO checksums that you generated match, but don't match the checksum from the .hash file, then something fishy may well be going on! As above, please let us know about that ASAP. Again, by posting on the forums, or emailing to support@turnkeylinux.org.

Comments

xcb567's picture

A simple md5sum would be quite useful, since some of us don't want to bother with GPG

Anonymous's picture

I, too, think that providing us with an MD5 sum would be nice. PGP is a big pain for me, but MD5 is quite simple. Yeah, it's easier to fake up something (like a malware-infested distro) with MD5 than with PGP, but I just want to know if it downloaded correctly. If it's been maliciously modified, then it's been maliciously modified, but it's a VM and it won't have direct access to my actual computer, so if it's got a problem, I can roll it back a few snapshots, or I can just wipe out the whole VM.

Liraz Siri's picture

I'll look into updating the signature files in the next release with MD5 / SHA1 hashes.
rinring's picture

gpg is easy to use, no problem, even though I didn't know before. :)

The problem is that the vmdk file for the wordpress appliance is corrupted and the signature isn't good either :/.

ikeo's picture

This page should be SSL-protected. If not, you are asking me to trust a signing key that has no proof it is authentic. SSL protection by itself is still not all that much more reassurance, but at least it lets me know I'm really talking to the genuine Turnkey Linux website and not some false site.
 

Hi,

This guide looks like it was created some time in 2011. Either the .sig build needs updating to be correct or the guide needs updating in at least the case of turnkey-lxc-14.1-jessie-amd64.iso.sig.

When I run:

gpg --keyserver hkp://keyserver.ubuntu.com --recv-keys 0xA16EB94D

I get back:

gpg: requesting key A16EB94D from hkp server keyserver.ubuntu.com
gpg: key A16EB94D: public key "Turnkey Linux Release Key <release@turnkeylinux.com>" imported
gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
gpg: depth: 0  valid:   1  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 1u
gpg: Total number processed: 1
gpg:               imported: 1  (RSA: 1)


which looks alright to me, though I have never used gpg before.

then:

gpg --list-keys 0xA16EB94D

pub   2048R/A16EB94D 2008-08-15 [expires: 2023-08-12]
uid                  Turnkey Linux Release Key <release@turnkeylinux.com>


which matches, so good. But:

gpg --verify turnkey-lxc-14.1-jessie-amd64.iso.sig
gpg: Signature made Sun 10 Apr 2016 22:15:46 AEST using RSA key ID A16EB94D
gpg: Good signature from "Turnkey Linux Release Key <release@turnkeylinux.com>"
gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.
Primary key fingerprint: 694C FF26 795A 29BA E07B  4EB5 85C2 5E95 A16E B94D
gpg: WARNING: not a detached signature; file 'turnkey-lxc-14.1-jessie-amd64.iso' was NOT verified!


and:

gpg --verify turnkey-lxc-14.1-jessie-amd64.iso.sig turnkey-lxc-14.1-jessie-amd64.iso
gpg: not a detached signature


So it looks like something is amiss with the .sig build to me. I haven't tried any other builds. At my end:

gpg --version
gpg (GnuPG) 1.4.21
Copyright (C) 2015 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Home: ~/.gnupg
Supported algorithms:
Pubkey: RSA, RSA-E, RSA-S, ELG-E, DSA
Cipher: IDEA, 3DES, CAST5, BLOWFISH, AES, AES192, AES256, TWOFISH,
        CAMELLIA128, CAMELLIA192, CAMELLIA256
Hash: MD5, SHA1, RIPEMD160, SHA256, SHA384, SHA512, SHA224
Compression: Uncompressed, ZIP, ZLIB, BZIP2

uname -a
Linux localhost 4.8.2-pclos1 #1 SMP Sun Oct 16 13:27:47 CDT 2016 x86_64 x86_64 x86_64 GNU/Linux

If you need any other info, just let me know.

Cheers,

David