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. From v0.6.1 on, the same file is also published as luksbox-x86_64-windows-setup.exe, a link that always serves the newest stable release (likewise luksbox-x86_64-windows.msi and luksbox-x86_64-windows.zip).
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.6.1, LUKSbox releases are still in the third tier (unsigned). The .exe / .msi is built from public source on a GitHub Actions runner, with artifact provenance attested via GitHub artifact attestations (see Verifying the download 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 "https://github.com/penthertz/LUKSbox/releases/latest/download/SHA256SUMS.txt" -OutFile SHA256SUMS.txt
Get-Content SHA256SUMS.txt | Select-String "luksbox-.*\.msi"
# Compare the two hashes (Get-FileHash prints upper case, the file lower case).

# Provenance: proves the file was built by the project's release workflow
gh attestation verify luksbox-x86_64-windows.msi --owner penthertz

Known Windows quirks

• One process per vault. While a vault is mounted or open in one LUKSbox process, a second open of it fails with "vault locked by another process". Unmount or close it first.
• Mountpoint is required. Pass a free drive letter (luksbox mount my.lbx Z:, add --fido2 etc. to unlock with a hardware key) or a path that does not exist yet. An existing folder fails with STATUS_OBJECT_NAME_COLLISION.
• luksbox mount runs in the background (0.6.1+). You unlock the vault in the terminal as before (passphrase, FIDO2, TPM prompts), then a hidden luksbox process takes over the WinFsp mount and you get the prompt back. Your passphrase never reaches that process, and closing the terminal or pressing Ctrl-C in it does not touch the mount. deniable-mount works the same way. Pass -f (--foreground) to keep the mount in the terminal as in earlier versions, where Ctrl-C unmounts.
• Unmounting. Run luksbox umount Z: (0.6.1+, from the same Windows session). It takes only the drive letter, not the vault file, and it returns once the vault is flushed and closed, so you can run another luksbox command or unplug the drive right after it.
• FIDO2 PIN. Windows asks for your security key's PIN in its own Windows Hello / security-key prompt, so since 0.6.1 LUKSbox (CLI, wizard and GUI) no longer asks for it as well. Earlier versions asked for it too and ignored what you typed there.
• Rotating the master key (luksbox rotate-mvk, or the wizard's rotation) failed on Windows in 0.6.0-rc.1 with "another process has locked a portion of the file" (os error 33) and changed nothing. It works again in 0.6.1.

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 the vault with a passphrase, then add a TPM-bound slot
# (identical slot kinds to Linux; a TPM slot cannot be the first one)
luksbox create my.lbx
luksbox enroll my.lbx --kind tpm2        # or tpm2-pin, 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.