docs(content): update self-check and binary verification docs

- clarify self-check mechanism for different platforms
- add details about platform-specific binary signing
- improve security notes and recommendations
- update code signing information for all platforms
- enhance build verification documentation

2 files changed, 106 insertions, 39 deletions

diff --git a/src/content/docs/advanced/app-self-check.md b/src/content/docs/advanced/app-self-check.md
index c22095a..773cff5 100644
--- a/src/content/docs/advanced/app-self-check.md
+++ b/src/content/docs/advanced/app-self-check.md
@@ -4,30 +4,38 @@ sidebar:
   label: Application Self-Check
 ---
 
-When Self-Check is enabled, GpgFrontend validates the digital signatures of its
-core dynamic libraries and components at startup. This ensures that the
-application’s essential code has not been altered, replaced, or
-corrupted—whether accidentally or through malicious interference.
+When Self-Check is enabled, GpgFrontend will verify the digital signatures
+(Authenticode signatures) of its core dynamic libraries and components at
+startup. This helps ensure that the application’s essential code has not been
+altered, replaced, or corrupted—whether accidentally or through malicious
+interference.
+
+This mechanism is particularly useful when running a copy of GpgFrontend from a
+USB drive or any other removable media that may be more susceptible to
+tampering. By validating the digital signatures of critical libraries at
+startup, Self-Check helps ensure that all essential dependencies of GpgFrontend
+remain intact and trustworthy, even in less secure or portable environments.
 
 :::tip[Note]
 
-The Application Self-Check feature is available starting from version
-2.1.9. In earlier versions, this integrity verification mechanism is not
-present.
+The Application Self-Check feature is available starting from version 2.1.9. In
+earlier versions, this integrity verification mechanism is not present. This
+feature is currently only effective on Windows platforms. On other operating
+systems, such as macOS and Linux, runtime self-check is not implemented.
 
 :::
 
 ## How It Works
 
-- During the build process, a cryptographic key pair is generated automatically
-  for each build.
-- The application libraries (DLLs) are signed using the private key, and only
-  the corresponding public key is embedded within the application resources.
-- After signing, the private key is discarded, making it impossible to forge new
-  signatures for tampered binaries.
-- At runtime, GpgFrontend verifies each critical library against its signature
-  using the embedded public key. If any library fails validation, a warning is
-  displayed and the issue is logged.
+- During the distribution process, application binaries (such as EXE and DLL
+  files) are digitally signed using a code signing certificate trusted by the
+  Windows operating system, utilizing the Windows Authenticode mechanism.
+- At startup, GpgFrontend checks the Windows digital signature of each critical
+  dynamic library and main executable, using the operating system’s native
+  signature validation (WinVerifyTrust).
+- If any library fails validation, a warning is displayed and the issue is
+  logged. This can alert users or administrators to possible tampering or
+  corruption.
 
 ## Enabling Self-Check
 
@@ -43,27 +51,57 @@ integrity check at startup.
 
 ## Build Requirements
 
-- The self-check signing process requires the `GPGFRONTEND_SIGN_BUILT_BINARY`
-  parameter to be set during the build. This triggers the generation of the
-  signing key pair and the signing of all relevant binaries.
-- The signing key pair is unique to each build. The private key is securely
-  deleted after signing, ensuring that no one—including the developers—can
-  generate valid signatures for modified or malicious binaries.
+- You must ensure that all Windows binaries (EXE, DLL) are properly code-signed
+  using a valid Authenticode certificate during your build or packaging process.
+- The self-check feature does not generate or embed any additional cryptographic
+  keys; it simply validates the standard Authenticode signatures at runtime.
 
 ## Platform Compatibility
 
-- Windows: The self-check feature is currently effective only on Windows
-  platforms. On Windows, dynamic library files are stable after build and
-  signing, allowing signature verification to work reliably.
-- macOS and Linux: Due to common post-build modifications such as codesign,
-  rpath adjustment, or packaging processes (e.g., AppImage, Flatpak), dynamic
-  library files on macOS and Linux often change after build. As a result,
-  digital signatures become invalid, and self-check is not currently effective
-  on these platforms.
+### Windows
+
+Self-Check uses Windows Authenticode signatures and WinVerifyTrust, providing
+reliable digital signature verification for EXE/DLL files.
+
+### macOS
+
+On macOS, all application binaries are signed using Apple-recognized developer
+certificates and go through Apple Notarization. The Gatekeeper security feature
+verifies both the signature and the notarization status of your application
+bundle upon installation and launch, ensuring integrity and authenticity.
+
+Thus, the application’s authenticity and integrity are protected at the system
+level, although the internal self-check feature does not perform additional
+runtime verification.
+
+### Linux
+
+For AppImage packages, there is currently no standard built-in self-check or
+signature verification mechanism similar to Authenticode or Apple Notarization.
+Integrity relies primarily on GPG signature checks during download and
+installation, but runtime self-validation is not possible.
+
+Flatpak packages use their own signature and sandboxing mechanisms, which offer
+a certain degree of integrity protection within the Flatpak ecosystem.
 
 ## Security Note
 
-The Application Self-Check adds an important layer of security by helping to
-ensure that GpgFrontend’s executable code remains authentic and untampered. It
-is particularly recommended for security-sensitive deployments or when running
+Application Self-Check adds an important layer of security by helping ensure
+that GpgFrontend’s executable code remains authentic and untampered on Windows.
+This is particularly valuable for security-sensitive deployments or when running
 GpgFrontend on shared or potentially untrusted systems.
+
+The self-check mechanism specifically verifies the integrity of core dynamic
+libraries, including GpgFrontend’s own libraries, OpenSSL libraries, and key Qt
+modules. It does not verify the main application executable (.exe) itself, as
+runtime tampering of the running process is not a practical attack vector for
+this component.
+
+For highly sensitive environments, users are strongly advised to use the
+operating system’s built-in tools to check the digital signature of the main
+executable file before launching the application.
+
+Where possible, administrators should consider configuring Windows security
+policies (e.g., AppLocker, WDAC) to only allow the loading of code-signed .exe
+and .dll files, ensuring that only trusted binaries can be executed or loaded
+into memory.
diff --git a/src/content/docs/appendix/code-binary-verify.md b/src/content/docs/appendix/code-binary-verify.md
index c585449..4ff95ae 100644
--- a/src/content/docs/appendix/code-binary-verify.md
+++ b/src/content/docs/appendix/code-binary-verify.md
@@ -2,7 +2,7 @@
 title: Code & Binary Verify
 ---
 
-To enhance the security and integrity of software distribution, it's crucial for
+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
@@ -18,13 +18,40 @@ 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.
 
-## Binary File Verification
+## Platform-Specific Binary Signing
 
 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.
 
+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:
+
+### Windows
+
+All executable files (.exe, .dll) and installer packages are signed using a
+Certum code signing certificate. The signature is trusted by Windows and can be
+verified through standard Windows mechanisms (e.g., file properties or
+signtool).
+
+### 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.
+
+### 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.
+
 ## Build Info Verification
 
 Our software includes an "About" interface accessible from the help menu,
@@ -58,7 +85,9 @@ dbaEG0FOTKu+n4rVhBpTes93Bn2GcRSbQwA=
 -----END PGP PUBLIC KEY BLOCK-----
 ```
 
-This comprehensive approach to security, including automated builds, careful
-selection of third-party libraries, and transparent verification methods,
-ensures that users can trust the software they are using while also providing
-the tools needed to verify that trust independently.
+This comprehensive approach to security—including automated builds,
+cross-platform code signing (Windows Authenticode, Apple codesign &
+notarization, OpenPGP for Linux), careful selection of third-party libraries,
+and transparent verification methods—ensures that users can trust the software
+they are using while also providing the tools needed to independently verify
+that trust.