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 https://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 +sha256sums+ or - for repositories - the +Packages+ files to establish a chain
  21 of trust: The SHA256 checksum will verify the integrity of the actual file
  22 while the signature will verify the integrity of the file containing the
  23 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
  34   *link:signatures.html[fingerprints page]*.
  35 . Download the firmware image into the same directory as the +sha256sums+ file
  36   and verify its checksum using the following command:
  37   +sha256sum -c --ignore-missing sha256sums+
  38
  39 === Verification script
  40
  41 You can use our supplied link:scripts/download.sh[convenience script] to
  42 automate the required download and signature verification steps.
  43
  44 Below is an example transcript of using the +download.sh+ script.
  45
  46 ----
  47 user@host:~$ wget http://lede-project.org/scripts/download.sh
  48 --2016-08-02 12:16:32--  http://lede-project.org/scripts/download.sh
  49 Connecting to lede-project.org... connected.
  50 HTTP request sent, awaiting response... 200 OK
  51 Length: 4091 (4,0K) [application/x-sh]
  52 Saving to: ‘download.sh’
  53
  54 download.sh         100%[===================>]   4,00K  --.-KB/s    in 0s
  55
  56 2016-08-02 12:16:32 (622 MB/s) - ‘download.sh’ saved [4091/4091]
  57
  58 user@host:~$ chmod +x download.sh
  59 user@host:~$ ./download.sh https://downloads.lede-project.org/snapshots/targets/ar71xx/generic/lede-ar71xx-generic-tl-wr1043nd-v1-squashfs-factory.bin
  60 1) Downloading image file
  61 =========================
  62 ############################################################ 100,0%
  63
  64 2) Downloading checksum file
  65 ============================
  66 ############################################################ 100,0%
  67
  68 3) Downloading the GPG signature
  69 ================================
  70 ############################################################ 100,0%
  71
  72 4) Verifying GPG signature
  73 ==========================
  74 The signature was signed by a public key with the id
  75 F93525A88B699029 which is not present on this system.
  76
  77 Provide a public keyserver url below or press enter to accept the
  78 default suggestion. Hit Ctrl-C to abort the operation.
  79
  80 Keyserver to use? [hkp://pool.sks-keyservers.net] >
  81 gpg: requesting key 8B699029 from hkp server pool.sks-keyservers.net
  82 gpg: key 626471F1: public key "LEDE Build System (LEDE GnuPG key for unattended build jobs) <lede-adm@lists.infradead.org>" imported
  83 gpg: Total number processed: 1
  84 gpg:               imported: 1  (RSA: 1)
  85 gpg: Signature made Di 02 Aug 2016 10:10:40 CEST using RSA key ID 8B699029
  86 gpg: Good signature from "LEDE Build System (LEDE GnuPG key for unattended build jobs) <lede-adm@lists.infradead.org>"
  87 gpg: WARNING: This key is not certified with a trusted signature!
  88 gpg:          There is no indication that the signature belongs to the owner.
  89 Primary key fingerprint: 54CC 7430 7A2C 6DC9 CE61  8269 CD84 BCED 6264 71F1
  90      Subkey fingerprint: 6D92 78A3 3A9A B314 6262  DCEC F935 25A8 8B69 9029
  91
  92 5) Verifying SHA256 checksum
  93 ============================
  94 lede-ar71xx-generic-tl-wr1043nd-v1-squashfs-factory.bin: OK
  95
  96 Verification done!
  97 ==================
  98 Firmware image placed in '/home/user/lede-ar71xx-generic-tl-wr1043nd-v1-squashfs-factory.bin'.
  99
 100 Cleaning up.
 101 user@host:~$
 102 ----
 103
 104
 105 === Developer information
 106
 107 Developers participating in the LEDE project need to provide both _GnuPG_ and
 108 _usign_ public keys which are stored in the central
 109 https://git.lede-project.org/?p=keyring.git[keyring.git] repository.
 110
 111 Refer to the link:/keygen.html[key generation howto] page for instruction on how to
 112 generate suitable signing keys.