WSL/Building in OBS

Content of an Appx file

The format to ship Windows apps via the Microsoft store is an Appx package. An Appx package is literally a zip file with some extra meta data and a cryptographic signature. In the context of WSL the Appx package context looks as follows:

 openSUSE-Tumbleweed.exe [1]
 install.tar.gz          [2]
 images/icon.ico         [3]
 Assets/*.png            [4]
 Resources.pri           [4]
 AppxManifest.xml        [5]
 AppxBlockMap.xml        [6]
 [Content_Types].xml     [6]
 AppxSignature.p7x       [7]

[1] The launcher

An EXE file based on Microsofts sample implementation. This program is installed on Windows and launched after installation to prepare the distro. Later it can be called directly to start an instance of the WSL "chroot" of the given distro.

[2] The compressed tarball of an openSUSE system

bash, zypper, yast etc are in there

[3-4] Assets for the Appx installer

Windows provides some generic user interface for installing Appx packages. Resources for that installer can be found in the Assets directory. The Resources.pri file is some binary format with an index of the assets. It can be created only on Windows using Visual Studio right now.

[5] Meta data for the installer

The manifest file provides some data to the generic Appx installer. Such as name of the app, vendor, architecture and icons. The attribute Publisher in that file is important for the cryptographic signature. Documentation about the format of this file can be found at Microsoft.

[6] Meta data for the installer

Those files are also for the installer but are automatically created by the appx tool.

[7] Authenticode signature

The cryptographic signature of the Appx package

Building WSL Appx packages in OBS

Building the WSL appx package as well as the Windows EXE file contained in the app follows common openSUSE standards. That means the components are build inside OBS in a fully automatic, unattended and reproducible way.

The devel project for the WSL app itself and closely related tools in OBS is Virtualization:WSL. The MinGW toolchains are available in the base distribution and maintained in OBS under the windows:mingw project space.

The following diagram outlines the relation of the various components in the build process:

Kiwi currently does not support creating appx packages itself, therefore the process includes some hacks to make the build possible nevertheless. As soon as Kiwi support for appx arrives the process will be simplified.

WSL-Distrolauncher

The launcher is compiled using a gcc cross compiler that produces Windows binaries on Linux (mingw64-cross-gcc).

fb-util-for-appx

The fb-util-for-appx utility is used to create the Appx package and the AppxBlockMap.xml in it. The signing feature of the utility is not used. OBS does that itself

kiwi-images-wsl

a regular kiwi image build. It installs Linux rpms into a chroot environment and packs everything into tarball.

containment-rpm-docker

a special hack to package the kiwi generated tarball of the Linux system into an rpm package so it can be used as dependency of other rpms.

wsl-appx

Using fb-util-for-appx this package takes the repackaged, kiwi generated tarball, some appx specific metadata and resources like icons as well as WSL-Distrolauncher to produce the actual appx file that can be installed on Windows.

The resulting appx file gets signed automatically by OBS with a certificate stored inside OBS.

Special Project Setup

In OBS terms there is a difference between building images (ie kiwi) vs building packages (ie rpmbuild). Each repository in a project has to have its build type configured. The default is to build packages. By convention kiwi images in official projects are built in the images repository which takes packages from the standard repository. Kiwi images are considered an end product that is published. Packages cannot depend on images. However, in order to produce an appx image, the wsl-appx package actually needs the kiwi generated image. Therefore, the containment-rpm-docker hack wraps the image in an rpm for wsl-appx to BuildRequire. In order for that to work the order of repositories is reversed in openSUSE:Factory:WSL. So the standard repo that contains wsl-appx actually builds against images in order to have access to the rpm produced by kiwi-images-wsl.

In the devel project a different solution is used in order to avoid a third repository. There a special aggregation package is used to copy back the kiwi generated rpm from the images repo to the standard repo.

Signing

In order for Windows to accept an Appx package it needs to be cryptographically signed. By default Windows only accepts signatures made by Microsoft during the submission process to the store. Therefore itis not possible to fully automatically produce Appx packages that can be installed on an off the shelf Windows machine.

It is possible to sign Appx packages with custom certificates though and import those as trusted root certs into Windows. So just as rpms, Appx packages built with the openSUSE build service get signed by a project specific key. The certificate containing the key can then be imported into Windows to trust it.

Special attention has to be paid to the subject of the certificate. The subject of the certificate has to match the Publisher attribute in the AppxManifest.xml file. Normal OBS projects have an automatically generated certificate with a project specific subject. For example:

 $ osc signkey --sslcert Virtualization:WSL|openssl x509 -noout -subject
 subject=CN = Virtualization OBS Project, emailAddress = Virtualization@build.opensuse.org

Therefore AppxManifest.xml needs to be adjusted according to target project. The wsl-appx package takes care of that.

Appx packages that are meant to be submitted to the Microsoft store need a special publisher value assigned by Microsoft though. The original certificate and key with that value is kept by Microsoft though so OBS cannot sign Appx packages with the same certificate as the Windows Store. In order to at least have an AppxManifest.xml file that is usable for upload to the store, the OBS projects for building the official openSUSE WSL Appx packages use a specially crafted certificate with a subject that matches Microsoft's certificate. When uploading the OBS built Appx package to the store, Microsoft then only replaces the digital signature.

Release Process

While the actual packages reside in openSUSE:Factory, the images are built in openSUSE:Factory:WSL due to the special repository setup mentioned earlier. The WSL images are built on top of the Factory snapshot repository aka Tumbleweed. That is to make sure the created WSL app package consists only of packages that already passed the Tumbleweed quality gates. That however means that any changes to any WSL related package only has an effect on the WSL images after TW was published.

Once a new WSL appx package is built, the image gets automatically copied to openSUSE:Factory:WSL:ToTest and synced to openQA for testing. If all tests are green, the build gets released to the download server.

Future Workflow

The following diagram shows the work flow as soon as kiwi gains support for generating appx files itself:

In the new workflow the containment-rpm-docker hack is no longer required. Now the wsl-appx package no longer produces the appx file but rather packages resources and metadata that is then consumed by kiwi.