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:

As of v0.5.2, LUKSbox releases are still in the third tier (unsigned). The .exe / .msi is built reproducibly from public source on a GitHub Actions runner, with artifact provenance attested via GitHub artifact attestations (see the Verifying the download section below). That gives cryptographic proof of where the binary came from, but Windows SmartScreen ignores attestations, it only honours its own reputation database of Authenticode-signed binaries.

A SignPath Foundation OV code-signing pipeline is already wired into CI over a trusted-build-system flow (the artifact's repository, workflow, and commit are provenance-verified through a GitHub App before signing), but it stays disabled until the production certificate is issued. Once it turns on, the "Unknown publisher" wording is replaced by the verified SignPath Foundation publisher; the blue popup can still appear on a fresh release until reputation accrues, because it is an OV certificate and not EV.

What we're doing about it

1. GitHub artifact 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 via SignPath Foundation (wired, not yet active). A free OV certificate for open-source projects, applied in CI with build provenance verified through a GitHub App. Enables automatically once the production cert lands; it clears the "Unknown publisher" wording, though the blue popup still accrues reputation.
3. EV Authenticode signing (possible future step). An EV cert is the only tier SmartScreen trusts from publication day one, with no reputation wait, but it needs a hardware token / HSM and a paid yearly cert. We may pursue it if the OV reputation ramp proves too slow for users.

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 2.0 hardware-bound keyslots on Windows

Since v0.5.0, the full TPM keyslot matrix works on Windows, at parity with Linux: Tpm2Sealed, the PIN-protected Tpm2SealedPin (chip-enforced dictionary-attack lockout), the fused Tpm2Fido2 (TPM AND authenticator, via Windows Hello or a physical key), the hybrid-pq-tpm2 / hybrid-pq-tpm21024 combos (TPM + ML-KEM seed file), and the three-factor hybrid-pq-tpm2-fido2 / hybrid-pq-tpm2-fido21024. The CLI, the interactive wizard, and the GUI all expose them on Windows exactly as on Linux.

The chip is reached through TBS (TPM Base Services), the broker built into every supported Windows, so no driver, admin rights, or code signing are needed for TPM access. The TPM chip is guaranteed on Windows 11 hardware (part of the launch floor). Slot bytes are TCG-standard TPM2B_* structures, byte-identical to the Linux build's, so the same physical chip unseals a vault regardless of which OS sealed it.

# Confirm the chip is present
Get-Tpm

# Create a TPM-bound vault (identical slot kinds to Linux)
luksbox create my.lbx --kind tpm2
luksbox create my.lbx --kind tpm2-pin
luksbox create my.lbx --kind tpm2-fido2

On a VM, enable the virtual TPM in your hypervisor (Hyper-V, VMware, VirtualBox all expose one). If a TPM operation reports a lockout, reset it from an elevated PowerShell; never run Clear-Tpm, which wipes the owner hierarchy and permanently destroys every TPM slot in your vaults. As on Linux, always pair a TPM slot with a backup passphrase or FIDO2 slot: a cleared or replaced chip makes the TPM slot unrecoverable. See the TPM 2.0 keyslots guide for the full matrix and the design record in docs/TPM_FUTURE_IMPROVEMENTS.md.