Install on Windows

Self-extracting installer bundle (default), plain MSI, portable zip, WinFsp prerequisite, Windows Hello support.

Prerequisites

Bundle installer -setup.exe (recommended)

The luksbox-<version>-x86_64-windows-setup.exe artifact is a WiX Burn bundle: it chains the official WinFsp 2.0.23075 MSI (if WinFsp isn't already installed) followed by the LUKSbox MSI. One download, one click, both components installed at once.

1. Download luksbox-<version>-x86_64-windows-setup.exe from GitHub Releases.
2. Run it. The bundle UI walks through:
   • "WinFsp 2.0.23075 - Windows kernel filesystem driver required for LUKSbox's 'Mount as volume' feature (skipped if already installed)"
   • LUKSbox itself. UAC will prompt once for the WinFsp kernel driver install.
3. Open a new terminal window (PATH is reread on shell launch):

   luksbox --version
   

The bundled WinFsp MSI is the upstream Authenticode-signed binary from https://github.com/winfsp/winfsp/releases (signed by NAVIMATICS LLC); the CI verifies the signature at bundle-build time. You can opt out of the chained WinFsp install with luksbox-<version>-x86_64-windows-setup.exe InstallWinFsp=0 (e.g., if you manage WinFsp via Group Policy or Chocolatey).

Plain MSI installer (admin / unattended)

For admins managing WinFsp separately (GPO, Chocolatey, Intune) or for unattended deploys via msiexec /i ... /qn:

1. Install WinFsp first: https://winfsp.dev/rel/ - run winfsp-2.0.msi. The LUKSbox MSI's Launch condition probes HKLM\SOFTWARE\WOW6432Node\WinFsp\InstallDir and refuses to install if WinFsp is absent.
2. Download luksbox-<version>-x86_64-windows.msi from GitHub Releases.
3. Run it (interactive) or msiexec /i luksbox-<version>-x86_64-windows.msi /qn (silent).
4. Open a new terminal window:

   luksbox --version
   

Portable .zip (no install)

For users who can't install software (locked-down enterprise machines, sandboxed setups):

# PowerShell
Invoke-WebRequest -Uri "https://github.com/penthertz/LUKSbox/releases/latest/download/luksbox-x86_64-windows.zip" -OutFile luksbox.zip
Expand-Archive luksbox.zip -DestinationPath .\luksbox
.\luksbox\luksbox.exe --version

The portable build ships winfsp-x64.dll next to luksbox.exe so the binary can launch without crashing, but the mount subcommand still needs WinFsp installed system-wide because it registers a kernel driver. If your locked-down environment forbids kernel driver installs, you can still create / open / extract vaults from the portable build; only the "mount as a Windows volume" feature is unavailable.

First launch and the blue Windows-protected-your-PC dialog

When you run a freshly-downloaded luksbox.exe, luksbox-gui.exe or luksbox-*.msi, Windows shows a blue SmartScreen dialog:

Windows protected your PC Microsoft Defender SmartScreen prevented an unrecognized app from starting. Running this app might put your PC at risk.

Click More info -> Run anyway. The .exe / .msi launches and SmartScreen does not bother you again on subsequent runs of the same binary.

Why SmartScreen warns

Windows code-signing has two trust tiers:

LUKSbox releases are currently in the third tier. We're a small project; the .exe is built reproducibly from public source on a GitHub Actions runner, with the artifact provenance attested via GitHub Sigstore Attestations (see the Verifying the download section below). That gives you cryptographic proof of where the binary came from, but Windows SmartScreen ignores Sigstore - it only honours its own internal reputation database of Authenticode-signed binaries.

What we're doing about it

The roadmap, in increasing cost and effectiveness:

1. GitHub Sigstore attestations (already shipping). Lets you verify the .exe came from a tagged CI run on a specific commit SHA via gh attestation verify <file> --owner penthertz. Does nothing for SmartScreen but covers the supply-chain question.
2. OV Authenticode signing (likely next). Around $80-300/year from Sectigo / DigiCert / SSL.com. Replaces "Unknown publisher" in the dialog with Verified publisher: Penthertz, but the blue warning still shows until reputation accrues.
3. EV Authenticode signing (the real fix). $200-500/year, plus a hardware token (FIPS-certified USB / HSM / Azure Key Vault). SmartScreen recognises EV-signed binaries from publication day one - the blue dialog stops appearing immediately for the very first user who downloads a release.

EV is the destination but the cost + the hardware-token CI plumbing are non-trivial for a pre-1.0 project. For now, the Run anyway click is a one-time-per-binary friction we accept in exchange for keeping the project fully open-source and free.

What you can do today

• Verify the SHA-256 of the .exe / .msi against the release notes' Markdown table before clicking Run anyway. The table is generated in CI, signed via GitHub's release token, and served from HTTPS - so a tampered binary downloaded from a hostile mirror would mismatch.
• Or use gh attestation verify for cryptographic provenance (see Verifying the download below).
• Once you've cleared SmartScreen for one binary, subsequent launches are silent. The friction is once per release, not once per launch.

Why WebAuthn (not raw libfido2) on Windows

LUKSbox on Windows uses Microsoft's webauthn.dll rather than talking USB-HID directly. Two reasons:

1. No admin required. Since Windows 10 1903, the FIDO HID device class is reserved for the WebAuthn system service. A non-admin process trying to read \\.\HID\\#VID_... gets access denied. webauthn.dll mediates without admin.
2. Windows Hello support comes for free. The same webauthn.dll API routes USB security keys, NFC keys, and the platform authenticator (PIN/fingerprint/face) through the same call. Pass --fido2-device windows://hello to target the platform authenticator specifically.

Verifying the download

Get-FileHash luksbox-*.msi -Algorithm SHA256
Invoke-WebRequest -Uri ".../SHA256SUMS.txt" -OutFile SHA256SUMS.txt
Get-Content SHA256SUMS.txt | Select-String "luksbox-.*\.msi"
# Compare hashes manually, or use gpg verify the .asc as on Linux/macOS
gpg --verify SHA256SUMS.txt.asc SHA256SUMS.txt

Known Windows quirks

• VaultLocked error on a second concurrent open of the same vault returns the raw OS error 33 ("the process cannot access the file") rather than LUKSbox's mapped Error::VaultLocked variant. Lock enforcement IS working; the error message is just less actionable. Cosmetic, no security impact.
• Drive-letter mounts require the letter to be free. Use luksbox mount my.lbx Z: to mount at Z:; the letter releases on luksbox umount Z:.

TPM-style hardware-bound keyslots on Windows

LUKSbox's hardware-bound keyslot kinds (Tpm2Sealed, the PIN-protected Tpm2SealedPin, the fused Tpm2Fido2, and the four hybrid-PQ-TPM variants combining TPM with ML-KEM-768/1024) are Linux-only for now. The Windows port is on the roadmap.

Implementation path: tcti-tbs.dll (Windows TPM Base Services) wrapped through the TctiNameConf::Tbs variant added in tss-esapi 8.0.0-alpha.2. Same on-disk wire format as the Linux side, so a vault sealed on Windows with the same chip would unseal on Linux. No code signing required for TPM access - the Authenticode signing on the MSI installer is unrelated to chip access. See docs/TPM_FUTURE_IMPROVEMENTS.md for the full evaluation of the three candidate implementation paths and why TBS won.

Blocking the immediate ship: tss-esapi 8.0 is still alpha, and the tpm2-tss floor jumps to 4.1.3, which would force older Linux LTS users onto a bundled-tpm static-linking path. We're tracking the trade-off and will likely ship Windows TPM either when 8.0 stable lands OR when there's clear user demand to take the alpha-pin risk.

For the moment, Windows users get passphrase / FIDO2 / hybrid-PQ keyslots. The FIDO2 path uses Windows Hello (TPM-backed via webauthn.dll) for the unlock factor itself, so the Hello PIN + your authenticator already provide a TPM-anchored unlock - just not the explicit --tpm2 slot kind a Linux user would enroll. A vault enrolled with --kind tpm2 on Linux is invisible to Windows, but other slots in the same vault unlock normally.