signing.txt

   1 ---
   2 ---
   3 Release Signing
   4 ===============
   5
   6 == Signing Approach
   7
   8 LEDE uses both https://www.gnupg.org/[GnuPG] and _usign_, a derivate of the
   9 OpenBSD http://www.openbsd.org/papers/bsdcan-signify.html[_signify_] utilitiy.
  10
  11 The _OPKG_ package manager uses _usign_ Ed25519 signatures to verify repository
  12 metadata when installing packages while release image files are usually signed
  13 by one or more developers with detached GPG signatures to allow users to verify
  14 the integrity of installation files.
  15
  16 Our _usign_ signature files carry the extension +.sig+ while the detached
  17 GPG signatures end with +.gpg+.
  18
  19 Note that not every file is signed individually but that we're signing the
  20 +md5sums+ and +sha256sums+ or - for repositories - the +Packages+ files to
  21 establish a chain of trust: The SHA256 checksum will verify the integrity of the
  22 actual file while the signature will verify the integrity of the file containing
  23 the checksums.
  24
  25 === Verify download integrity
  26
  27 In order to verify the integrity of a firmware download you need to do the
  28 following steps:
  29
  30 . Download the +sha256sum+ and +sha256sum.gpg+ files
  31 . Check the signature with +gpg --with-fingerprint --verify sha256sum.gpg
  32   sha256sum+, ensure that the GnuPG command reports a good signature and that
  33   the fingerprint matches the ones listed on our fingerprints (TODO:link) page.
  34 . Download the firmware image and calculate its hash using one of the
  35   +sha256sum+ or +openssl sha256+ commands.
  36 . Verify that the calculated checksum matches the one listed in the +sha256sums+
  37   file.
  38
  39 You can use the example script below to verify the integrity of image downloads,
  40 call it as +./script.sh https://downloads.lede-project.org/path/to/image.bin+
  41
  42 ----
  43 #!/bin/bash
  44
  45 [ -n "$1" ] || {
  46         echo "Usage: $0 <url>" >&2
  47         exit 1
  48 }
  49
  50 finish() {
  51         echo "Cleaning up."
  52         rm -r "/tmp/verify.$$"
  53         exit $1
  54 }
  55
  56 trap "finish 7" INT TERM
  57
  58 destdir="$(pwd)"
  59 image_url="$1"
  60 image_file="${image_url##*/}"
  61 sha256_url="${image_url%/*}/sha256sums"
  62 gpgsig_url="${image_url%/*}/sha256sums.gpg"
  63
  64 mkdir -p "/tmp/verify.$$"
  65 cd "/tmp/verify.$$"
  66
  67 echo "1) Downloading image file"
  68 echo "========================="
  69 wget -O "$image_file" "$image_url" || {
  70         echo "Failed to download image file!" >&2
  71         finish 1
  72 }
  73
  74 echo "2) Downloading checksum file"
  75 echo "============================"
  76 wget -O "sha256sums" "$sha256_url" || {
  77         echo "Failed to download checksum file!" >&2
  78         finish 2
  79 }
  80
  81 echo "3) Downloading the GPG signature"
  82 echo "================================"
  83 wget -O "sha256sums.gpg" "$gpgsig_url" || {
  84         echo "Failed to download GPG signature!" >&2
  85         finish 3
  86 }
  87
  88 echo "4) Verifying GPG signature"
  89 echo "=========================="
  90 gpg --with-fingerprint --verify "sha256sums.gpg" "sha256sums" || {
  91         echo "Failed to verify checksum file with GPG signature!" >&2
  92         finish 4
  93 }
  94
  95 echo ""
  96 echo "5) Verifying SHA256 checksum"
  97 echo "============================"
  98 remote_csum="$(grep -F "SHA256($image_file)=" "sha256sums")"
  99 local_csum="$(openssl sha256 "$image_file")"
 100 [ "$remote_csum" = "$local_csum" ] || {
 101         echo "Checksums do not match!" >&2
 102         echo "REMOTE: $remote_csum" >&2
 103         echo "LOCAL:  $local_csum" >&2
 104         finish 5
 105 }
 106
 107 cp "$image_file" "$destdir/$image_file" || {
 108         echo "Failed to write '$destdir/$image_file'" >&2
 109         finish 6
 110 }
 111
 112 echo ""
 113 echo "Verficiation done!"
 114 echo "=================="
 115 echo "Firmware image placed in '$dest_dir/$image_file'."
 116
 117 finish 0
 118 ----
 119
 120
 121 === Developer information
 122
 123 Developers participating in the LEDE project need to provide both _GnuPG_ and
 124 _usign_ public keys which are stored in the central
 125 https://git.lede-project.org/?p=keyring.git[keyring.git] repository.
 126
 127 Refer to the link:/keygen.html[key generation howto] page for instruction on how to
 128 generate suitable signing keys.