Whonix ™ Windows Installer - Design Documentation

From Whonix
Jump to navigation Jump to search

Work in progress.

Design / Features[edit]


  • new implementation of whonix.exe in lazarus (without NET framework)
  • platform independent ( later linux/mac version possible )
  • ui consists of two forms ( main & error )
  • main form has two buttons for start/stop and manage Whonix VMs
  • error form pops up if virtualbox is missing


  • installs windows version of WhonixStarter
  • adds start menu entry
  • adds desktop shortcut
  • uninstall over Windows "Programs and Features" tool


  • ui consists of a main form with several pages guiding the user through the installation process
  • platform independent ( later linux/mac version possible )
  • installs VirtualBox and WhonixOVA
  • executes WhonixStarterSetup.msi (Windows only)
  • checks installed and only reinstall missing components
  • does not uninstall or delete any component


  • Whonix .ova is bigger than 2 GB.
  • Windows .cab files have a hardcoded 2 GB maximum file size.


  • cross compile on Debian (source) for Windows (target)
  • building does not require Windows

Build limitations:

  • needs Debian bookworm or above because of minimal wixl and lazarus version

flow chart[edit]

(1) Whonix-Starter:

  • lazbuildWhonixStarter.lprWhonixStarter.exe
  • wixlWhonixStarterSetup.wxsWhonixStarter.exe, WhonixStarterSetup.wxsWhonixStarterSetup.msi

(2) Whonix-Installer:

  • lazbuildWhonixSetup.lprWhonixSetup.exe
  • WhonixSetup.exe + append + Whonix.ovaWhonixSetup-XFCE.exe




code signing[edit]


EV (extended validation) certificate required to avoid Microsoft SmartScreen Filter warning message.


  • EV code signing for Windows authenticode to avoid Microsoft SmartScreen Filter warning message.
  • cross signing
  • build scripts running on Debian Linux
  • build result (program) running on Windows 64 bit
  • avoid running proprietary closed source software on local build machine
  • can be fully automated using build scripts
  • avoid hardware token (compatibility, hassle)
  • avoid proprietary closed source device drivers
  • ideally avoid non-mainline Linux kernel drivers
  • supports signing big files



  • asked





Google Cloud HSM;



Reminder: Always please merge first before developing further.

new file location - FYI[edit]

ppcross_install has been moved.


FYI (for your interest) only. This ticket (wiki chapter) can be deleted after reading.

Feel free to use this wiki page as a notepad for developers too by making notes somewhere else outside the TODO chapter.

avoid use of lazarus - replace with free pascal compiler[edit]

lazarus is an IDE, but not a compiler, right?

Can use of lazarus on command line be avoided?

(It can stay in the script as comment but out commented by default.)

Reason: Simplification; avoid dependency installation

Can the command be replaced with the free pascal compiler instead?


no, we need the binary lazbuild to compile a lazarus project from cmd, which is part of lazarus. fpc is the compiler, thats right, but it has not all the dependencies of WhonixStarter/Installer. it is impossible to compile this project without the LCL.

document ppcross_install[edit]

Why is ppcross_installarchive.org needed even on Debian bookworm?

Is it because Debian doesn't compile with "make crossinstall"?

The fp-compiler (fpc) manpagearchive.org states:


Tells the compiler to generate a script that can be used to assemble and link on the host system, not on the target system. Use this when cross-compiling.


Tells the compiler to generate a script that can be used to assemble and link on the target system, not on the host system. Use this when cross-compiling.

Does that help?

Otherwise can this be reported against Debian as a question, a bug or feature request? If yes, please write a draft for a feature request. (Patrick will review and post it.)

Bug report probably already exists: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=845498archive.org

Does this help...? https://gist.github.com/o11c/cf98115ba716ebdd1dc2cc75b290f321archive.org


fpc is a kind of wrapper that redirects to the cross/compiler. we could use ppcx64 to compile from linux 64bit to windows 64bit, but it cannot found the windows system units without the install_ppcross() steps in the script. it generates the needed precompiled windows units in /usr/lib/fpc/X.X.X/units/x86_64-win64

if a debian package with this files exists somewhere in the wild we could use this instead.

avoid use of git clone[edit]


abolish need to fetch from https://gitlab.com/freepascal.org/fpc/source.gitarchive.org

just use the existing compiler from Debian[edit]

fpc -Twin64 -Fi/usr/share/fpcsrc/3.2.2/rtl/win64 -Fi/usr/share/fpcsrc/3.2.2/rtl/win -Fi/usr/share/fpcsrc/3.2.2/rtl/inc -Fi/usr/share/fpcsrc/3.2.2/rtl/x86_64 -Fu/usr/share/fpcsrc/3.2.2/rtl/win64 -Fu/usr/share/fpcsrc/3.2.2/rtl/inc -FU/tmp/rtl -FE/tmp test

based on fpc source package[edit]

Could it be based on apt-get source?

apt-get source fpc

Contains same contents as https://salsa.debian.org/pascal-team/fpcarchive.org? No. Debian does some modifications.archive.org Lacks Makefile.fpc, which can be re-generated.

Can we edit https://salsa.debian.org/pascal-team/fpc/-/blob/master/debian/rulesarchive.org to add cross compilation? Maybe not even needed.

debian/rules is a makefile.

make -f debian/rules

It supports ifdef (similar to an environment variable) CROSSOPT. On Debian source packages are usually built using dpkg-buildpackage. It might be as simple as setting the correct environment variables. Here's an untested attempt.

sudo apt build-dep fpc

CROSSINSTALL=1 CROSSOPT="OS_TARGET=x86_64 CPU_TARGET=win64" dpkg-buildpackage

Setting the environment variable might be more complicated than initially editing debian/rules manually.

maybe helpful: https://wiki.debian.org/PortsDocs/BootstrappingFPCarchive.org

regenerate Makefile.fpc


fpcmake -w -Tall

fpcmake -w -Tx86_64-win64

based on fpc-source binary package[edit]

Less promising approach.

sudo apt install fpc-source

sudo apt install fpc-source -t bullseye-backports

cd /usr/share/fpcsrc

cd /usr/share/fpcsrc/3.2.2/compiler/


building on Debian stable - bullseye[edit]

building Whonix-Installer on Debian stable - bullseye[edit]


+ lazbuild -B WhonixSetup.lpr --cpu=x86_64 --os=win64 --compiler=/usr/bin/ppcrossx64
CopySecondaryConfigFile /etc/lazarus/environmentoptions.xml -> /home/user/.lazarus/environmentoptions.xml
Error: (lazbuild) project has no main unit
Error: Process completed with exit code 2.


building Whonix-Starter on Debian stable - bullseye[edit]


+ lazbuild -B Whonix.lpr --cpu=x86_64 --os=win64 --compiler=/usr/bin/ppcrossx64
CopySecondaryConfigFile /etc/lazarus/environmentoptions.xml -> /home/user/.lazarus/environmentoptions.xml
Error: (lazbuild) project has no main unit
Error: Process completed with exit code 2.


See Also[edit]

We believe security software like Whonix needs to remain open source and independent. Would you help sustain and grow the project? Learn more about our 10 year success story and maybe DONATE!