Skip to content

Code & Binary Verify

When you download software, one question matters: is this really the app the developer made, or did someone change it on the way to you?

For a security tool, that question matters even more. This page shows how you can check your copy of GpgFrontend, and how far you can go. To learn how releases are built, signed and published, see How Releases and Updates Work.

Find the kind of download you have:

You have How to check it
A stable release with a .sig file Check a Stable Release
A test build, beta or release candidate Check a Test Build
The Windows installer Windows checks it too. See Windows.
The macOS app macOS checks it for you. See macOS.
Flatpak, an app store or a package manager The store or package manager checks it for you.

Since version 1.0.5, every stable release file is signed with the maintainer’s OpenPGP key. Next to each download there is a small .sig file. With GnuPG (the gpg command), you can use it to check that the file is genuine and was not changed by anyone.

The key shown below signs every release from v2.1.5 on. Older releases were signed with earlier keys, so this fingerprint does not match them.

  1. Download the maintainer’s public key from bktus.com/openpgp.

  2. Import it into GnuPG. You can also do this in GpgFrontend itself.

  3. Check that the key’s fingerprint is exactly:

    12F7E8858CF15BEC9975FF3C5CA3DA246843FD03

The same fingerprint is listed in the security policy of the repository, so you can compare the two.

  1. Put your download and its .sig file in the same folder.

  2. Open a terminal in that folder and run this command. Replace FILE with the name of your download:

    Terminal window
    gpg --verify FILE.sig FILE
  3. GnuPG should say Good signature, made by the key with the fingerprint above.

Any other result means the file is not the one that was published. Do not use it.

Each system also adds its own check on top of the signature.

The stable installers are signed with a Certum code signing certificate. Windows checks this signature itself. You can also look at it: right-click the file, open Properties, and look at Digital Signatures.

The app is signed with an Apple developer certificate and passes Apple’s notarization check. macOS verifies both automatically the first time you open the app. If the app had been changed, macOS would refuse to start it.

The AppImage comes with a .sig file, like the other packages. Check it with GnuPG before you run the app, as shown in Check a Stable Release. Flatpak and distribution packages are checked by their own tools when you install them.

There are three kinds of test build. A nightly build is made from the newest code. A beta is a test build of the next fix release of one series. A release candidate is an early test version of the next feature release, like 2.4.0-rc.1. None of them is signed with the maintainer’s OpenPGP key, so they have no .sig files. The files are not signed one by one either.

Instead, the check has two parts:

  • SHA256SUMS.txt is the checksum list. A checksum is a short fingerprint of a file. If the file changes, the checksum changes. This list has the checksum of every file in the build.
  • SHA256SUMS.txt.sigstore.json is the signature of that list. The project’s build on GitHub makes it with Sigstore, a free signing service for open source projects.

First you check that the list really comes from the project’s build. Then you check your file against the list.

Get the files from the test versions on the Downloads page. Pick the test version, then open More download options. The two checking files are linked at the bottom.

This step needs the cosign tool. Put SHA256SUMS.txt and SHA256SUMS.txt.sigstore.json in the same folder. Open a terminal in that folder and run:

Terminal window
cosign verify-blob SHA256SUMS.txt --bundle SHA256SUMS.txt.sigstore.json \
--certificate-identity https://github.com/saturneric/GpgFrontend/.github/workflows/build.yml@refs/heads/main \
--certificate-oidc-issuer https://token.actions.githubusercontent.com

If it prints Verified OK, the checksum list was signed by this project’s build on GitHub, from the main branch. The signature is also written to Rekor, a public log that anyone can search.

Any other result means the list is not the one that was published. Do not use the build.

The command above is for a nightly build. The other test builds are signed from another place, so change the end of the --certificate-identity line:

Build Replace refs/heads/main with
A beta of series 2.2 refs/heads/release/2.2
The release candidate 2.4.0-rc.1 refs/tags/v2.4.0-rc.1

Put your download in the same folder as SHA256SUMS.txt. Open a terminal in that folder and run the command for your system.

Run the Linux command in Git Bash or WSL:

Terminal window
sha256sum -c --ignore-missing SHA256SUMS.txt

Your file should be listed with OK. Because Step 1 showed that the list comes from the project’s build, your file is covered too. If your file is missing or shows FAILED, do not use it.

The checks above are enough for everyday use. But if your safety, your freedom or your work depends on this software, hold it to a higher standard: do not use any prebuilt binary at all, not even ours.

Every prebuilt binary asks you to trust the machines and services that built it. For most people that trust is reasonable. In a truly critical situation, you can remove it: build the app yourself, from source code you have checked.

If you are in that situation, this is the path:

  1. Get the source, not a binary. Clone the repository and check out an official release tag. Release tags made by the current release process (v2.3.0 and later) are signed. Verify the signature with git verify-tag and the maintainer’s key from bktus.com/openpgp. The tags of v2.2.4 and older releases are not signed.
  2. Read before you build. Review the code yourself, or have someone you trust review it. Pay attention to the build scripts too, not only the app code.
  3. Build on a machine you trust. Use a clean, freshly installed system used only for this build. Install the compiler and libraries from your operating system’s official repositories. Keep the machine offline once everything is downloaded, if you can.
  4. Keep your own record. Note the commit hash you built and the checksums of what you produced, so you can tell later whether anything changed.

Build instructions are in the contributing guide. This path costs real time and skill. That is the honest price of not having to trust anyone else’s build.