Document PGP release signature usage

[maltfield]

Expected behaviour

When I go to download the latest version of libusb, I should also see instructions on how to verify the authenticity of the file after download and before install. Or, at least, a link to the document that describes this.

Actual behaviour

I see no mention about cryptographic authenticity verification on the download page on GitHub

• https://github.com/libusb/libusb/releases/tag/v1.0.27

I see no mention about cryptographic authenticity verification on the download page on SourceForge:

• https://sourceforge.net/projects/libusb/files/libusb-1.0/libusb-1.0.27/

I see no mention about cryptographic authenticity verification on the "Downloads" section of the libusb wiki:

• https://github.com/libusb/libusb/wiki#user-content-Downloads

I see no mention about cryptographic authenticity verification on the "FAQ" section of the libusb wiki:

• https://github.com/libusb/libusb/wiki/FAQ

I see no mention about cryptographic authenticity verification on the website:

• https://libusb.info/

Steps to reproduce

1. Go to https://github.com/libusb/libusb/
2. Click Releases
3. Download libusb-1.0.27.tar.bz2
4. Download libusb-1.0.27.tar.bz2.asc
5. Look around for information on where to get the authentic Release Signing PGP Key for the libusb project
6. ???
7. Get confused and open ticket

Additional Context

I would recommend adding a new page to your wiki that:

1. Writes-out the full fingerprint of the Release Signing Key
2. Link to a URL where the user can download the Release Signing Key
3. Give the gpg command for how a user can fetch the Release Signing Key from the keyservers
4. Links to all the other domains that write-out the full fingerprint of the Release Signing Key (so the user can cross-verify out-of-band)

After the above documentation page is complete, add at least one link to it from the following pages:

• https://github.com/libusb/libusb/releases/tag/v*
• https://sourceforge.net/projects/libusb/files/libusb-1.0/libusb-*
• https://github.com/libusb/libusb/wiki#user-content-Downloads
• https://github.com/libusb/libusb/wiki/FAQ
• https://libusb.info/

[maltfield]

I also recommend adding a KEYS file to the root of your repo (located along-side files like COPYING and AUTHORS), per the KEYS standard established by Apache

• https://infra.apache.org/release-signing#keys-policy

For more best-practices, see also:

1. https://infra.apache.org/release-signing
2. https://docs.opendev.org/opendev/system-config/latest/signing.html
3. https://wiki.debian.org/Subkeys
4. https://riseup.net/en/security/message-security/openpgp/best-practices

[mcuee]

Reference:

• Fix Release Signatures on PyPI (404 Not Found) vpelletier/python-libusb1#96

And then compare libusb-1.0.27 release and python-libusb1 3.1.0 release, I do not see any difference in terms of the source code archive signing.
https://github.com/libusb/libusb/releases/tag/v1.0.27
https://github.com/vpelletier/python-libusb1/releases/tag/3.1.0

What is missing here?

[mcuee]

I also recommend adding a KEYS file to the root of your repo (located along-side files like COPYING and AUTHORS), per the KEYS standard established by Apache

I do not see any repos I am involved doing that (eg: libusb, pyusb, avrdude, openocd, libftdi, hidapi, etc).

[maltfield]

I do not see any repos I am involved doing that (eg: libusb, pyusb, avrdude, openocd, libftdi, hidapi, etc).

Check Maven. 100% of the packages on Apache Maven's central repository are cryptographically signed with PGP. The KEYS standard is best-practice per Apache.

[maltfield]

What is missing here?

Sorry if I was unclear: this ticket is asking for documentation. What's missing is documentation.

[mcuee]

I do not see any repos I am involved doing that (eg: libusb, pyusb, avrdude, openocd, libftdi, hidapi, etc).

Check Maven. 100% of the packages on Apache Maven's central repository are cryptographically signed with PGP.

At least I do not see anything like that in the official github repo. They do not even have signed source tarball.
https://github.com/apache/maven

[mcuee]

What is missing here?

Sorry if I was unclear: this ticket is asking for documentation. What's missing is documentation.

Could you provide a reference? Thanks.

[maltfield]

At least I do not see anything like that in the official github repo.

A good example is the Apache Ant KEYS file

• https://downloads.apache.org/ant/KEYS

They do not even have signed source tarball.

Maven signs their releases. You can find the signatures on their website:

• https://maven.apache.org/download.cgi#files

Note the text above the table, which provides info to users on how to verify signatures by linking to the documentation

In order to guard against corrupted downloads/installations, it is highly recommended to verify the signature of the release bundles against the public KEYS used by the Apache Maven developers.

The above text links to the following documentation, which is what this ticket is asking-for to be added to the libusb website and/or wiki:

• https://www.apache.org/info/verification.html#CheckingSignatures

Could you provide a reference? Thanks.

Does the above answer your question? If not, let me know and I can provide examples of such documentation from other projects, if you'd like.

[mcuee]

Does the above answer your question? If not, let me know and I can provide examples of such documentation from other projects, if you'd like.

Thanks for the answer.

I will let @tormodvolden decide how to address the issue you raised. He is in charge of the recent releases like 1.0.25/1.026/1.0.27.

[tormodvolden]

This is a good point. I have been signing with my key that is listed e.g. at https://launchpad.net/~tormodvolden but it is not mentioned anywhere on our pages.

[tormodvolden]

You have done a great job at documenting the issue, you're welcome to suggest some wording and templates as well.

[maltfield]

Here are some examples pages from open source projects documenting how their users can cryptographically verify their releases:

• https://www.apache.org/info/verification.html#CheckingSignatures
• https://docs.featherwallet.org/guides/linux#verifying-the-download-optional
• https://support.torproject.org/tbb/how-to-verify-signature/
• https://ubuntu.com/tutorials/how-to-verify-ubuntu
• https://tails.net/install/expert/index.en.html#verify-key
• https://calyxos.org/install/verify/#additional-verification

You can make this very complicated if you'd like, but at the minimum I think the documentation should:

1. Tell users that you sign your releases with PGP
2. Tell users where they can go to download the signatures of your releases
3. Write-out the full fingerprint of the PGP key that you use to sign releases
4. Link to at least 2 URLs (on distinct domains) where the user can download your release signing PGP public key (eg launchpad, keybase, github, gitlab, keys.openpgp.org, mastodon, libusb.info, etc)
5. Show an example execution of the verification with the CLI, including the gpg command and the full output

[mcuee]

I think the above seems to be a good practice.

On the other hand, I am also trying to understand why most projects do not even sign the release.

So I look at libusb github download number statistics, very few people actually downloaded the signature files. Very interestingly that Do.not.use.the.tar.gz.--.please.download.the.tar.bz.--.txt gets many more downloads than the signature files.

1. libusb-1.0.26 till today 17-Mar-2024
   v1.0.26
   Release Info:
   Published on: 2022-04-10
   Release Author: tormodvolden
   Downloads: 1,616,488
   Download Info:
   Do.not.use.the.tar.gz.--.please.download.the.tar.bz.--.txt (0 MiB)
   Last updated on 2022-04-10 — Downloaded 9,282 times
   libusb-1.0.26-binaries.7z (2.87 MiB)
   Last updated on 2022-04-10 — Downloaded 121,156 times
   libusb-1.0.26-binaries.7z.asc (0 MiB)
   Last updated on 2022-04-10 — Downloaded 2,321 times
   libusb-1.0.26.7z (2.4 MiB)
   Last updated on 2023-12-10 — Downloaded 1,737 times
   libusb-1.0.26.7z.asc (0 MiB)
   Last updated on 2023-12-10 — Downloaded 49 times
   libusb-1.0.26.tar.bz2 (0.59 MiB)
   Last updated on 2022-04-10 — Downloaded 1,479,712 times
   libusb-1.0.26.tar.bz2.asc (0 MiB)
   Last updated on 2022-04-10 — Downloaded 2,231 times

2. libusb 1.0.27 till today 17-Mar-2024
   Release Info:
   Published on: 2024-01-31
   Release Author: tormodvolden
   Downloads: 37,379
   Download Info:
   libusb-1.0.27.7z (3.91 MiB)
   Last updated on 2024-01-31 — Downloaded 8,922 times
   libusb-1.0.27.7z.asc (0 MiB)
   Last updated on 2024-01-31 — Downloaded 128 times
   libusb-1.0.27.tar.bz2 (0.61 MiB)
   Last updated on 2024-01-31 — Downloaded 28,162 times
   libusb-1.0.27.tar.bz2.asc (0 MiB)
   Last updated on 2024-01-31 — Downloaded 167 times

[tormodvolden]

It is understandable that the signatures are not downloaded often if we don't tell explain what they are and how to use them. I also think the download numbers are skewed by bots downloading whatever (comes first?), and build scripts etc.

[maltfield]

I am also trying to understand why most projects do not even sign the release.

Unfortunately, security is an afterthought for most software developers.

If you don't sign your releases, then your users cannot know if they downloaded the "authentic version" or a "malicious version" of your software. https does not protect users from supply-chain attacks such as Publishing Infrastructure Compromise. This is especially a concern for libraries, which is a tasty target for malicious actors to poison the library and downstream software projects (watering hole attack).

Many open source projects have learned this lesson the hard way. Here is a (incomplete) list of some historic instances of supply chain security incidents that affected various software projects in the past years:

• https://github.com/cncf/tag-security/tree/main/supply-chain-security/compromises

[maltfield]

@tormodvolden for right now (as a workaround) where can users download your PGP public key? And what is the full fingerprint?

The latest libusb release appears to be signed with a key = AA0639079EFB61B9, but that doesn't match any of the three keys listed on your launchpad link:

1. C68187379B23DE9EFC46651E2C80FF56C6830A0E
2. 32EAC3AA2932F7F152850C2A0ECA153961EC0EEC
3. C68187379B23DE9EFC46651E2C80FF56C6830A0E

Also there's no link on your launchpad page to download the actual PGP public key.

[tormodvolden]

Yes, the third key (you listed it as number 1 also but that must have been a copy-pasto) with fingerprint C681 8737 9B23 DE9E FC46 651E 2C80 FF56 C683 0A0E is the correct public key. If you download this one the signature on the releases will be verified. But you are right it is not obvious just looking at the key id used for signing, unless you click on the key on the launchpad page so that you can recognize AA0639079EFB61B9 being a (signing) subkey of the primary one.

The keys listed on the search result page are download links.

Also, if you search for AA0639079EFB61B9 on https://keys.openpgp.org the result (with click to download) is C68187379B23DE9EFC46651E2C80FF56C6830A0E.

But yes, we can make this clearer and have the fingerprints listed on our web pages.

[maltfield]

Thanks

unless you click on the key on the launchpad page

Where exactly do you click? The fingerprints are not clickable for me on the launchpad page

if you search for AA0639079EFB61B9 on https://keys.openpgp.org

Unfortunately it is not possible to download and import your key from this website. Try it on a fresh VM, and you get the error

user@disp8480:~/Downloads$ gpg --import C68187379B23DE9EFC46651E2C80FF56C6830A0E.asc 
gpg: directory '/home/user/.gnupg' created
gpg: keybox '/home/user/.gnupg/pubring.kbx' created
gpg: key 2C80FF56C6830A0E: new key but contains no user ID - skipped
gpg: Total number processed: 1
gpg:           w/o user IDs: 1
user@disp8480:~/Downloads$ 

The problem is that modern-day keyservers strip UIDs (for your data privacy) by default. And gpg refuses to import keys without a UID.

The solution is that you need to verify your email address by clicking the link sent to the uid of the key as described here:

• https://keys.openpgp.org/about

In the meantime, please let me know how I can download your PGP key.

[tormodvolden]

Looks like the fingerprints are not clickable unless you are logged in :(

But this is the URL and it seems publicly available: https://keyserver.ubuntu.com/pks/lookup?fingerprint=on&op=index&search=0xC68187379B23DE9EFC46651E2C80FF56C6830A0E