GPG, in plain words

GPG does two jobs: it signs things, so you can check who made them, and it encrypts things, so only the right person can read them. Wren Linux uses the first constantly. Everything it downloads from outside Debian is checked against a signing key pinned in pins.sh.

The one idea

Each person has two matching keys:

• A public key. Give it to anyone. It checks your signatures, and lets people encrypt to you.
• A private key. Never give it to anyone. It makes your signatures, and decrypts what's sent to you.

Keys have a long fingerprint, which identifies them. Names on a key prove nothing, because anyone can make a key with anyone's name. The fingerprint is what you check.

The most useful thing: check a download

Say you've downloaded a file and its signature, file.iso and file.iso.asc, and the maker's public key, maker.asc. Using a keyring just for this keeps your own tidy:

mkdir -m 700 check
gpg --homedir check --import maker.asc
gpg --homedir check --fingerprint
gpg --homedir check --verify file.iso.asc file.iso

Now look at two things:

1. The fingerprint matches one you got somewhere else, from a place an attacker wouldn't also control: the maker's site over https, a printed copy, or a friend. If the key and its fingerprint came from the same place as the download, whoever changed the file could have changed those too.
2. It says Good signature, with that fingerprint. Then delete the folder with rm -rf check.

You'll also see this:

WARNING: This key is not certified with a trusted signature!

It's normal. It means you haven't told GPG you trust this key. The check you just did by hand is what matters. What isn't normal is BAD signature: don't use that file.

Checking Wren Linux itself: SECURITY.md shows the fingerprint, and you can compare it with what's in your copy:

gpg --show-keys --fingerprint data/wren-signing-key.asc

Make your own key

gpg --full-generate-key

Press Enter for the default kind of key, and choose an expiry, such as 2y. You can extend it later, and if you ever lose the key, it stops being trusted by itself. The name and email go into the public key for anyone to see, so use only what you want linked to it. Use a long passphrase: it protects the key if someone copies your files.

Then find your fingerprint, and make a public copy to share:

gpg --fingerprint you@example.org
gpg --armor --export you@example.org > my-key.asc

Sign and encrypt

Sign a file. This makes notes.txt.asc, which anyone with your public key can check:

gpg --armor --detach-sign notes.txt
gpg --verify notes.txt.asc notes.txt

Encrypt a file to someone. First import their key and check its fingerprint, as above:

gpg --import their-key.asc
gpg --armor --encrypt --recipient them@example.org notes.txt

That makes notes.txt.asc. Only they can read it, and that includes you, unless you also add --recipient you@example.org. To read one sent to you:

gpg --output notes.txt --decrypt notes.txt.asc

Keep your key safe

A revocation certificate is how you tell the world the key is no longer yours, if you lose it or it's stolen. GPG makes one when it makes your key, in ~/.gnupg/openpgp-revocs.d/. You can also make one yourself, choosing a reason, which is easiest to do now, while you still have the key:

gpg --output revoke.asc --gen-revoke you@example.org

Then back up your private key to an encrypted USB stick, along with that certificate:

gpg --armor --export-secret-keys you@example.org > private-key.asc

Anyone with revoke.asc can cancel your key, and anyone with private-key.asc can try your passphrase, so don't leave either on an unencrypted disk. Delete the copies once they're on the stick.

What GPG doesn't protect

• It doesn't hide who's talking. An encrypted email still shows who it's from, who it's to, its subject and when it was sent. It also can't protect old messages if your key is stolen later. For conversation, use something made for it, such as Signal or SimpleX (wrenctl install signal).
• A signature says who, not whether it's safe. It proves the holder of a key signed this. It doesn't prove the file is harmless, or that the key wasn't stolen.
• Malware running as you can wait for you to type your passphrase. The threat model says more.

A simpler tool for files

To encrypt a file with a passphrase, or to someone's key, without any of this, Wren Linux includes age. It does one job:

age -p notes.txt > notes.txt.age
age -d notes.txt.age > notes.txt

How Wren Linux uses this

• pins.sh holds the fingerprint of every key it trusts, with the date each was checked and where.
• lib/appimage.sh checks downloads in a throwaway keyring holding only the one pinned key, so a second key slipped into a file doesn't count. An expired or revoked key's signature fails.
• update.sh takes an update only if the newest commit is signed by Wren Linux's key.
• extras/security-key.sh and extras/signing-key.sh are for keeping keys somewhere a program running as you can't simply read them.