gpg-verify

name	gpg-verify
description	Verify a GPG signature on a file or clear-signed text. Use when the user has downloaded a release artefact + `.sig`/`.asc` and wants to confirm authenticity, or received a clear-signed message and wants to check it. Distinguishes "good signature, untrusted key" from "good signature, trusted key" — both are cryptographically valid; only the latter proves identity.

Verify a GPG Signature

When to use

The user has a signature to verify:

• Detached signature: <file> + <file>.sig (or .asc).
• Clear-signed message: a single file containing both the text and the signature (-----BEGIN PGP SIGNED MESSAGE----- block).
• Signed-and-encrypted: handled automatically during gpg-decrypt.

Detached verification

gpg --verify <file>.sig <file>

Or, if the signature filename matches the data filename with a .sig / .asc suffix, GPG auto-detects:

gpg --verify <file>.sig

Clear-signed verification

gpg --verify <file>.asc

Prints Good signature from … and outputs the embedded message to stderr. To extract just the message body:

gpg --decrypt <file>.asc > message.txt

(Yes, --decrypt works on clear-signed text — it strips the signature wrapper while verifying.)

Reading the result

A passing verification prints something like:

gpg: Signature made <date>
gpg:                using EDDSA key ABCDEF1234567890
gpg: Good signature from "Real Name <[e-mail]>" [unknown]
gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no assurance this key belongs to the named user.
Primary key fingerprint: 1234 5678 ...

Three things to check:

1. Good signature — cryptographic check passed; the signature matches the data and the signing key.
2. Key fingerprint — compare to the fingerprint you obtained out-of-band (project website, prior signed message, key handed over in person). This is what proves identity. The cryptographic check alone doesn't.
3. Trust level — [unknown] / [marginal] is a warning, not a failure. If the user has independently confirmed the fingerprint, they can locally sign the key:

   gpg --lsign-key <fingerprint>
   

   Future verifications then show [full] and skip the warning.

Failure modes

• BAD signature — the file has been modified since signing, or the signature is corrupt. Do not trust.
• Can't check signature: No public key — you don't have the signer's public key on the keyring. Fetch it:

  gpg --keyserver keys.openpgp.org --recv-keys <KEYID>
  

  …or import from a .asc file the signer provided. Then re-run --verify.
• Signature made <date> ... key has expired — signature is mathematically valid but was made with an expired key. Up to the user whether to trust depending on context (was it signed before expiry?).

Verifying release artefacts

Standard pattern:

gpg --keyserver keys.openpgp.org --recv-keys <PROJECT-KEYID>
gpg --verify release-1.2.3.tar.gz.sig release-1.2.3.tar.gz

Confirm the printed fingerprint matches the project's published signing-key fingerprint. Don't skip the fingerprint compare — anyone can upload a key claiming to be the project.