Code Signing & Release Integrity
Relevant source files
The following files were used as context for generating this wiki page:
Zephyr implements a multi-layered integrity system to ensure that all released binaries, core updates, and database assets remain untampered. This system combines official Authenticode signing for Windows distributions with cryptographic signature verification (Minisign) and SHA-256 hashing for all automated updates.
The project follows a "Security First" philosophy, enforcing strict host whitelisting and atomic file operations during the update process to prevent partial or malicious writes.
Sources: SECURITY.md:183-195, FEATURES.md:104-109
Windows Code Signing
Zephyr utilizes SignPath.io to provide free code signing for official Windows release artifacts. This process ensures that the installer or executable originates from a verified source and has not been modified since it was built.
Signing Scope and Roles
Only official Windows artifacts built via GitHub Actions are signed. These include:
- NSIS Setup installers (Full and Lite versions).
- MSI packages (Full and Lite versions).
- Portable executables.
The project maintainer manually approves every release signing request before the certificate is applied. Artifacts are submitted to SignPath directly from the repository's build workflow.
Sources: CODE_SIGNING_POLICY.md:1-16, FEATURES.md:126-128
Verification Procedure
You can verify the signature on Windows using PowerShell or the file property interface. A valid signature must list "SignPath Foundation" as the signer.
Get-ChildItem .\Zephyr_*.exe, .\Zephyr_*.msi -File -ErrorAction SilentlyContinue | Get-AuthenticodeSignature
Sources: CODE_SIGNING_POLICY.md:22-26
Update Integrity Verification
The Zephyr updater enforces a three-step verification process for every component it downloads, including the Mihomo core, Geo-database files, and the Zephyr client itself.
Verification Layers
- Trusted Host Check: The system only allows downloads from
github.comand its verified subdomains (api.github.com,objects.githubusercontent.com). - SHA-256 Hashing: Every downloaded file is hashed and compared against a digest fetched from a trusted source.
- Minisign Ed25519 Signatures: For client updates, the system verifies an Ed25519 signature against a hardcoded public key to ensure the installer is authentic.
Sources: apps/desktop/src-tauri/src/updater.rs:74-78, 629-631, FEATURES.md:104-106
Integrity Workflow Diagram
The following diagram illustrates the sequence of checks performed when downloading an update component.
The updater uses atomic file operations (rename swaps) to apply the update only after all verification steps succeed.
Sources: apps/desktop/src-tauri/src/updater.rs:710-743, FEATURES.md:107-109
Component-Specific Security
Different components have specific size limits and verification requirements summarized in the table below:
| Component | Max Size | Primary Verification | Reliability Mechanism |
|---|---|---|---|
| Mihomo Core | 100 MB | SHA-256 Digest | mihomo -t pre-check |
| Geo-Databases | 100 MB | SHA-256sum File | Dual-file atomic apply |
| Zephyr Client | 200 MB | Minisign Ed25519 | SignPath Authenticode |
| Metadata/JSON | 10 MB | TLS Integrity | Dual-source race check |
Sources: apps/desktop/src-tauri/src/updater.rs:253, 335, 638, FEATURES.md:46-47
Minisign Signature Verification
For client self-updates, the system fetches a .minisig file. The minisign_verify.rs module handles the parsing and validation of these signatures.
| Variable/Step | Description |
|---|---|
MAX_SIG_SIZE | Hard limit of 4096 bytes for signature files to prevent memory exhaustion. |
Trusted Host | Only permits signature downloads from the github.com domain. |
verify_minisign_signature | Validates the downloaded installer against the Ed25519 signature. |
Sources: apps/desktop/src-tauri/src/updater.rs:1143-1166, apps/desktop/src-tauri/src/minisign_verify.rs:1-10
Atomic Update and Rollback Logic
To prevent application corruption during updates, Zephyr uses a transactional atomic swap pattern. This ensures that if a binary replacement or core restart fails, the previous working version is restored.
- Temporary Extraction: The new binary is extracted to a UUID-named temporary file (e.g.,
mihomo_uuid.tmp). - Backup Creation: The existing binary is renamed to a backup file (
mihomo.backup). - Atomic Swap: The temporary file is renamed to the target executable path.
- Health Check: The system attempts to start the core. If it fails, the backup is renamed back to the primary path.
Sources: apps/desktop/src-tauri/src/updater.rs:770-805, FEATURES.md:91-93
Summary
Release integrity in Zephyr is maintained through a combination of external signing authorities (SignPath) and internal cryptographic controls (Minisign and SHA-256). By enforcing size limits, domain restrictions, and atomic transactions, the system protects users from malicious updates and corrupted installations.
Sources: SECURITY.md:191-195, FEATURES.md:126-128