Skip to content

BUILDING.md

Latest commit

 

History

History
89 lines (72 loc) · 4.58 KB

BUILDING.md

File metadata and controls

89 lines (72 loc) · 4.58 KB
Raw

Building SynchronousAudioRouter

This repo ships a verifiable WDK build pipeline (.github/workflows/build.yml) plus two helper scripts under tools/. The goal is a reproducible, unsigned, submission-ready driver package that can then be signed for free via OSSign or Microsoft attestation signing. The build itself never signs anything — signing is a separate, later step.

What the pipeline produces

For each run, the driver job emits an artifact sar-driver-x64/ containing:

file purpose
SynchronousAudioRouter.sys the unsigned kernel driver
SynchronousAudioRouter.inf INF with a valid DriverVer stamped at build time
SynchronousAudioRouter.cat security catalog generated by Inf2Cat
SynchronousAudioRouter_x64.cab the package you submit for attestation signing
SHA256SUMS.txt SHA-256 of every payload file
BUILD-INFO.txt commit, version, platform, build time

On pushes to master/tags the job also produces a GitHub build-provenance attestation for the .sys, cryptographically linking the binary to the exact workflow run and source commit. Hashes + provenance are precisely the "source ↔ binary is verifiable" property OSSign asks for.

The usermode job builds the SarAsio.dll ASIO plugin for x64 and x86 (32-bit DAWs need the 32-bit DLL).

Local build

# One-time: install the WDK + its VS extension (needs VS2022 already present)
./tools/Install-WdkBuildEnv.ps1

# Build the driver (unsigned)
msbuild SynchronousAudioRouter.sln /t:SynchronousAudioRouter `
    /p:Configuration=Release /p:Platform=x64 /p:SignMode=Off /p:SpectreMitigation=false

# Stage, version-stamp, catalog, cab and hash it
./tools/Package-SarDriver.ps1 -Platform x64 -DriverVersion 0.13.2.0 -Describe local

Signing (the part the build deliberately skips)

A modified kernel driver does not inherit anyone else's signature; the package above must be signed before stock Windows will load it without test mode.

  1. For your own machine, right now (free): enable test signing (bcdedit /set testsigning on, reboot) and test-sign the .sys/.cat. Note the desktop watermark and that this breaks most anti-cheat games and requires Secure Boot off on Windows 11.
  2. For a clean, redistributable driver (free, the real goal): submit SynchronousAudioRouter_x64.cab to OSSign or, if you hold an EV certificate, to Microsoft Partner Center for attestation signing. The returned signature loads on stock Windows 11 with no test mode.

Known follow-ups (intentionally not done in iteration 1)

These are tracked here so nothing is silently missing:

  • ARM64. The INF has only [Standard.NTamd64] / [Standard.NTx86] models, so Inf2Cat cannot package ARM64. Add [Standard.NTARM64] (and the matching install/service sections) before enabling an ARM64 matrix entry. This is the step that matters for the Windows-on-Arm direction.
  • Spectre mitigation. The build passes /p:SpectreMitigation=false to stay green without the Spectre-mitigated runtime libs. For a production/attestation driver, install those libs (VS component Microsoft.VisualStudio.Component.VC.Runtimes.x86.x64.Spectre) and drop the flag so it builds with Spectre.
  • DriverVer in source. The committed INF still has the placeholder DriverVer=0.1; the pipeline stamps a valid value at build time but the source value should eventually be fixed too.
  • Installer (MSI). The WiX SarInstaller project is not built by this pipeline yet (needs the WiX 3.x toolset on the runner). The driver package is sufficient for signing; the MSI is a packaging convenience to add back later.
  • EWDK alternative. For maximum reproducibility you can swap the Install-WdkBuildEnv.ps1 step for a pinned Enterprise WDK ISO (a fully self-contained, version-locked build environment). That removes the dependency on the mutable runner image at the cost of a large ISO download per run.

Note on WDK/SDK version: the CI build does not hard-pin a version. The Build driver step auto-selects the highest SDK under Windows Kits\10\Include that actually carries the WDK kernel headers (km\ntifs.h) and passes it as WindowsTargetPlatformVersion. On today's windows-2022 image that resolves to 10.0.26100 (the SDK pinned in the .vcxproj, 10.0.22621.0, ships without the matching kernel headers, which is why pinning it broke the build). SDK_VERSION in the workflow and the param in tools/Install-WdkBuildEnv.ps1 are only a fallback-download hint for machines that have no WDK at all.