# Code signing & verifying your download

This page describes how YazSes release binaries are produced, signed and verified, so
that you can check a download is genuine before you run it.

!!! info "Current status — releases are not yet code-signed"

    As of **v2.18.0**, the Windows `.exe` and macOS `.dmg` are **unsigned**. Windows
    SmartScreen and macOS Gatekeeper will warn you. Code signing through the
    [SignPath Foundation](https://signpath.org) programme for open-source projects is
    being set up; this page documents the policy that governs it. Until then, verify
    downloads with the checksums described below.

## Why this matters

An installer you download from the internet can be tampered with between the project's
build server and your machine. Two independent mechanisms protect against that:

- **A checksum** proves the file you have is byte-for-byte the file the project
  published — provided you get the checksum from a trustworthy place.
- **A code signature** proves the file was produced by the project and has not been
  modified since, and is what stops your operating system from warning you.

## Verify a download with checksums

Every release publishes a `SHA256SUMS.txt` asset listing the hash of each artifact,
generated by the release workflow directly from the uploaded files.

=== "Windows (PowerShell)"

    ```powershell
    Get-FileHash .\YazSes-<version>-windows-x64.exe -Algorithm SHA256
    ```

=== "macOS / Linux"

    ```bash
    sha256sum --check --ignore-missing SHA256SUMS.txt
    ```

Compare the result against the matching line in `SHA256SUMS.txt` on the
[releases page](https://github.com/MSKazemi/yazses/releases). If they differ, **do not
run the file** — please [open an issue](https://github.com/MSKazemi/yazses/issues).

!!! note

    `SHA256SUMS.txt` is published from **v2.18.0 onwards**. For releases older than
    that, compare against the hashes recorded in the package manifests under
    [`packaging/`](https://github.com/MSKazemi/yazses/tree/main/packaging).

    If a release is missing an artifact for your platform, that artifact's line is
    simply absent — the checksum file lists what was actually published.

## Verify a code signature

Once signing is active, Windows releases are Authenticode-signed.

!!! warning "The publisher will read *SignPath Foundation*, not *MSKazemi*"

    This is expected and is not a sign of tampering. YazSes is signed through the
    SignPath Foundation's free code-signing programme for open-source projects. The
    certificate is issued to the Foundation, which acts as publisher on behalf of the
    project.

Right-click the `.exe` → **Properties** → **Digital Signatures**, or in PowerShell:

```powershell
Get-AuthenticodeSignature .\YazSes-<version>-windows-x64.exe | Format-List
```

You want `Status: Valid` and a signer certificate issued to **SignPath Foundation**.

## Signing policy

This is the policy the project commits to for every signed release.

**What gets signed.** Only artifacts built by the project's own GitHub Actions workflow
([`build-windows.yml`](https://github.com/MSKazemi/yazses/blob/main/.github/workflows/build-windows.yml))
from a tag on the public repository. Nothing built on a developer machine is ever
submitted for signing.

**Who approves.** Every signing request requires manual approval by the project
maintainer. Signing is not automatic on push.

**Key custody.** Signing keys are held in SignPath's HSM. No maintainer, no contributor
and no CI job ever has access to private key material — the build uploads an unsigned
artifact and receives a signed one back.

**Reproducibility.** Releases are cut only from tags on the public repository, so every
signed binary corresponds to a commit that anyone can inspect, and the build logs are
public.

**Reporting a problem.** If you encounter a YazSes binary whose signature does not
validate, or which your antivirus flags, please report it via
[GitHub Security Advisories](https://github.com/MSKazemi/yazses/security/advisories/new)
or by opening an issue.

## Why your antivirus may still complain

YazSes does two things that heuristic scanners associate with keyloggers, because they
are genuinely the same OS facilities:

- It installs a **global keyboard hook** so it can detect the press and release of your
  hold-to-talk key while another application has focus. It watches one configured key
  and never records, stores or transmits what you type.
- It **injects keystrokes** into the focused window — this is how transcribed text is
  delivered, and it is the entire output mechanism of any dictation tool.

Commercial dictation software (Dragon NaturallySpeaking, Talon Voice, Windows Voice
Access) uses the same two mechanisms. YazSes makes no outbound network connections
other than speech-model downloads you explicitly trigger; see the
[privacy statement](privacy-statement.md) and
[ADR-011](https://github.com/MSKazemi/yazses/blob/main/design/adr/adr-011.md), which
makes "nothing leaves the machine" a binding architectural constraint.

## SmartScreen

A newly signed application still shows a SmartScreen warning until it accumulates
download reputation — this happens to every new publisher and is not specific to
YazSes. Click **More info → Run anyway**. The warning shown for a *signed* application
is milder than the hard block shown for unsigned ones, and it fades as downloads
accumulate.

See also: [Install on Windows](windows-install.md) · [Privacy statement](privacy-statement.md)