signing.txt

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