---
---
Release Signing
===============

== Signing Approach

LEDE uses both https://www.gnupg.org/[GnuPG] and _usign_, a derivate of the
OpenBSD https://www.openbsd.org/papers/bsdcan-signify.html[_signify_] utilitiy.

The _OPKG_ package manager uses _usign_ Ed25519 signatures to verify repository
metadata when installing packages while release image files are usually signed
by one or more developers with detached GPG signatures to allow users to verify
the integrity of installation files.

Our _usign_ signature files carry the extension +.sig+ while the detached
GPG signatures end with +.gpg+.

Note that not every file is signed individually but that we're signing the
+sha256sums+ or - for repositories - the +Packages+ files to establish a chain
of trust: The SHA256 checksum will verify the integrity of the actual file
while the signature will verify the integrity of the file containing the
checksums.

=== Verify download integrity

In order to verify the integrity of a firmware download you need to do the
following steps:

. Download the +sha256sum+ and +sha256sum.gpg+ files
. Check the signature with +gpg --with-fingerprint --verify sha256sum.gpg
  sha256sum+, ensure that the GnuPG command reports a good signature and that
  the fingerprint matches the ones listed on our
  *link:signatures.html[fingerprints page]*.
. Download the firmware image into the same directory as the +sha256sums+ file
  and verify its checksum using the following command:
  +sha256sum -c --ignore-missing sha256sums+

=== Verification script

You can use our supplied link:scripts/download.sh[convenience script] to
automate the required download and signature verification steps.

Below is an example transcript of using the +download.sh+ script.

----
user@host:~$ wget http://lede-project.org/scripts/download.sh
--2016-08-02 12:16:32--  http://lede-project.org/scripts/download.sh
Connecting to lede-project.org... connected.
HTTP request sent, awaiting response... 200 OK
Length: 4091 (4,0K) [application/x-sh]
Saving to: ‘download.sh’

download.sh         100%[===================>]   4,00K  --.-KB/s    in 0s      

2016-08-02 12:16:32 (622 MB/s) - ‘download.sh’ saved [4091/4091]

user@host:~$ chmod +x download.sh 
user@host:~$ ./download.sh https://downloads.lede-project.org/snapshots/targets/ar71xx/generic/lede-ar71xx-generic-tl-wr1043nd-v1-squashfs-factory.bin
1) Downloading image file
=========================
############################################################ 100,0%

2) Downloading checksum file
============================
############################################################ 100,0%

3) Downloading the GPG signature
================================
############################################################ 100,0%

4) Verifying GPG signature
==========================
The signature was signed by a public key with the id
F93525A88B699029 which is not present on this system.

Provide a public keyserver url below or press enter to accept the
default suggestion. Hit Ctrl-C to abort the operation.

Keyserver to use? [hkp://pool.sks-keyservers.net] > 
gpg: requesting key 8B699029 from hkp server pool.sks-keyservers.net
gpg: key 626471F1: public key "LEDE Build System (LEDE GnuPG key for unattended build jobs) <lede-adm@lists.infradead.org>" imported
gpg: Total number processed: 1
gpg:               imported: 1  (RSA: 1)
gpg: Signature made Di 02 Aug 2016 10:10:40 CEST using RSA key ID 8B699029
gpg: Good signature from "LEDE Build System (LEDE GnuPG key for unattended build jobs) <lede-adm@lists.infradead.org>"
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: 54CC 7430 7A2C 6DC9 CE61  8269 CD84 BCED 6264 71F1
     Subkey fingerprint: 6D92 78A3 3A9A B314 6262  DCEC F935 25A8 8B69 9029

5) Verifying SHA256 checksum
============================
lede-ar71xx-generic-tl-wr1043nd-v1-squashfs-factory.bin: OK

Verification done!
==================
Firmware image placed in '/home/user/lede-ar71xx-generic-tl-wr1043nd-v1-squashfs-factory.bin'.

Cleaning up.
user@host:~$ 
----


=== Developer information

Developers participating in the LEDE project need to provide both _GnuPG_ and
_usign_ public keys which are stored in the central
https://git.lede-project.org/?p=keyring.git[keyring.git] repository.

Refer to the link:/keygen.html[key generation howto] page for instruction on how to
generate suitable signing keys.