diff options
Diffstat (limited to 'src/content/docs/appendix/code-binary-verify.md')
| -rw-r--r-- | src/content/docs/appendix/code-binary-verify.md | 104 |
1 files changed, 49 insertions, 55 deletions
diff --git a/src/content/docs/appendix/code-binary-verify.md b/src/content/docs/appendix/code-binary-verify.md index f378412..d66ab7f 100644 --- a/src/content/docs/appendix/code-binary-verify.md +++ b/src/content/docs/appendix/code-binary-verify.md @@ -1,78 +1,73 @@ --- title: Code & Binary Verify -description: "Verify the authenticity and integrity of GpgFrontend binaries using digital signatures and reproducible, automated GitHub Actions builds." +description: "How to check that your copy of GpgFrontend is genuine and untouched, from signed packages to building it yourself." sidebar: order: 2 --- -To enhance the security and integrity of software distribution, it’s crucial for -developers and users alike to employ methods for verifying the authenticity and -integrity of code and executable files. The process outlined below aims to -fortify trust in software distribution by leveraging digital signatures and -secure, automated build processes. +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? -## Automated Build Process +For a security tool, that question matters twice. This page shows how +GpgFrontend lets you check, and how deep you can go. -GpgFrontend leverages **GitHub Actions** for automated compilations, ensuring -that every binary file version released is directly compiled from the source -code stored in the GitHub repository's main branch. This approach guarantees -that the compilation process is transparent, replicable, and free from manual -interference. The exact commands and environment configurations used during the -compilation are documented within the project's `.github/workflow/release.yml` -file, allowing for full accountability and reproducibility. +## Nobody Builds the App by Hand -## Platform-Specific Binary Signing +Every official release is built by **GitHub Actions**, an automatic build +service. It takes the source code straight from the public repository, +compiles it, and publishes the result. No person builds release files on their +own computer and uploads them. -From version 1.0.5 onwards, I sign our packages containing the binary -executable files with a GPG key to further ensure security. Each package is -accompanied by a signature file in the release section (with a `.sig` suffix), -allowing users to verify the package before use using standard GPG tools. +The build recipe is public too, in the repository file +`.github/workflows/build.yml`. So anyone can see exactly how each release +was made, and anyone can repeat it. -All official binary releases are signed with a GPG key, providing a baseline -level of cross-platform integrity and authenticity verification. In addition to -GPG signatures, each platform incorporates its own native code signing and -verification mechanisms, as outlined below: +## Every Package Is Signed + +Since version 1.0.5, every release package is signed with the maintainer's +OpenPGP key. Next to each download there is a small `.sig` file. With standard +GPG tools, you can use it to check that the package is genuine and was not +changed by anyone. + +Each system also adds its own check on top: ### Windows -All executable files (.exe, .dll) and installer packages (.msi, .msix) are -signed using a [Certum](https://www.certum.eu/en/certum-by-asseco/) code signing -certificate. The signature is trusted by Windows and can be verified through -standard Windows mechanisms (e.g., file properties or signtool). +All programs and installers are signed with a +[Certum](https://www.certum.eu/en/certum-by-asseco/) code signing certificate. +Windows checks this itself. You can also look at it yourself: right-click the +file, open Properties, and look at Digital Signatures.  ### macOS -All application bundles and binaries are signed with an Apple-approved developer -certificate (codesign). Each official release also passes Apple Notarization, -ensuring the package’s integrity and compliance with Apple’s security standards. -Gatekeeper will automatically verify these protections on first launch. +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.  ### Linux -AppImage packages are provided with a GPG signature file (with a .sig suffix) in -the release section. Users are encouraged to verify the authenticity and -integrity of the package using the provided GPG public key before installation -or execution. For Flatpak and other formats, the platform’s own signature and -sandboxing mechanisms offer additional security. +The AppImage comes with a `.sig` file, like the other packages. Check it with +GPG before you run the app. Flatpak and other formats bring their own +signature and sandbox systems on top.  -## Build Info Verification +## Check Inside the App -Our software includes an "About" interface accessible from the help menu, -providing users with information about the software version, platform, and the -specific GitHub repository branch and commit hash used for compiling the binary. -This feature adds an extra layer of transparency and verification for users. +Open the About window from the Help menu. It shows the version, the platform, +and the exact branch and commit hash of the source code this copy was built +from. That lets you match your running app to a specific point in the public +code history.  -## Public Key for Verification +## The Signing Key -All commits and binary packages are signed with the maintainer's OpenPGP key. +All commits and release packages are signed with the maintainer's OpenPGP key. The key and its fingerprint are published at [bktus.com/openpgp](https://bktus.com/openpgp/). Get the key there, check the fingerprint, and use it to verify the `.sig` file that comes with each release. @@ -80,13 +75,12 @@ fingerprint, and use it to verify the `.sig` file that comes with each release. ## When the Stakes Are Very High 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. +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, it -is a risk you do not need to take, because you can remove it: build the app -yourself, from source code you have checked. +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: @@ -96,14 +90,14 @@ If you are in that situation, this is the path: 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. +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 -[development environment guide](/appendix/setup-dev-env/). This path costs real -time and skill. That is the honest price of not having to trust anyone else's -build. +[development environment guide](/appendix/setup-dev-env/). This path costs +real time and skill. That is the honest price of not having to trust anyone +else's build. |