diff options
Diffstat (limited to 'browser/installer/windows/docs/MSIX.rst')
| -rw-r--r-- | browser/installer/windows/docs/MSIX.rst | 226 |
1 files changed, 226 insertions, 0 deletions
diff --git a/browser/installer/windows/docs/MSIX.rst b/browser/installer/windows/docs/MSIX.rst new file mode 100644 index 0000000000..ec73d1950c --- /dev/null +++ b/browser/installer/windows/docs/MSIX.rst @@ -0,0 +1,226 @@ +MSIX Package +============ + +Firefox MSIX packages are full participants in the "modern" Windows +app packaging system. They are distributed, installed, updated, +repaired, and uninstalled entirely using that system. This gives +administrators lots of deployment options, and also grants complete +control over when and how application updates are rolled out +(Firefox's built-in updater is always fully disabled in MSIX +packages). This stands in contrast to Firefox MSI packages, which +mostly work against the Windows Installer framework rather than with +it, and therefore are missing a lot of important functionality; for +example, tools that install MSI packages generally cannot uninstall +Firefox [#]_. This means the MSIX package may well be the better +option for deploying to Windows 10 and up. + +In automation +------------- + +The ``repackage-msix`` and ``repackage-shippable-l10n-msix`` tasks +repackage the ZIP packages produced by signed build tasks into MSIX +packages. The ``shippable-l10n`` variants depend on Linux64 builds and +localization tasks to produce signed langpacks, which are incorporated +into the MSIX package as distribution extensions. (This is the same +approach taken by ``snap`` and ``flatpak`` Linux packages.) + +The ``repackage-signing-msix`` and +``repackage-signing-shippable-l10n-msix`` tasks sign the MSIX packages +produced by the repackage tasks. + +Signing in automation +~~~~~~~~~~~~~~~~~~~~~ + +MSIX packages are signed by the same certificates that sign binaries for +other jobs. In practice, this means that try builds are signed with the +```Mozilla Fake CA`` +certificate `MozFakeCA_2017-10-13.cer <https://raw.githubusercontent.com/mozilla-releng/OpenCloudConfig/3493a608bf700b68a54ff2fd506f33373bb87a04/userdata/Configuration/Mozilla%20Maintenance%20Service/MozFakeCA_2017-10-13.cer>`__. +In order to install try builds locally, you must trust this certificate. +**For your own security, it's best to do this in Windows Sandbox or a +Virtual Machine**. To do so run the following in an elevated +(administrator) Powershell: + +:: + + $ Import-Certificate -FilePath "MozFakeCA_2017-10-13.cer" -Cert Cert:\LocalMachine\Root\ + ... + Thumbprint Subject + ---------- ------- + FA056CEBEFF3B1D0500A1FB37C2BD2F9CE4FB5D8 CN=Mozilla Fake CA + +The ``shippable-l10n`` MSIX variants incorporate signed langpacks. These +in turn are signed with the same certificate. Firefox knows about this +certificate but does not trust it by default. To trust it, set the +hidden Gecko boolean preference + +:: + + xpinstall.signatures.dev-root=true + +Sadly, it's not possible to set preferences via a ``distribution.ini`` +early enough to impact loading the signed langpacks (see `Bug +1721764 <https://bugzilla.mozilla.org/show_bug.cgi?id=1721764>`__), and +once the signed langpacks fail to load once, they will not be reloaded +(see `Bug +1721763 <https://bugzilla.mozilla.org/show_bug.cgi?id=1721763>`__). This +make testing the first-run experience challenging. What can be done is +to install the MSIX package (perhaps using +``Add-AppxPackage -Path ...``) and determine the profile directory +(using ``about:support``). Uninstall the MSIX package (perhaps using +``Get-AppxPackage | Where -Property Name -like "Mozilla.*" | Remove-AppxPackage``). +Delete the contents of the profile directory entirely, but add a file +``user.js`` containing: + +:: + + user_pref("xpinstall.signatures.dev-root", true); + user_pref("extensions.logging.enabled", true); + +Reinstall the MSIX package and the signed langpacks should now be loaded +(slowly!) and available after first startup. + +Local developer builds +---------------------- + +``mach repackage msix`` lets you repackage a Firefox package (or +directory) into an MSIX/App Package. The main complication is that an +App Package contains channel-specific paths and assets, and therefore +needs to be branding-aware, much as an Android package needs to be +branding-aware. + +Usage +~~~~~ + +The tool is designed to repackage ZIP archives produced in automation. +Start looking for official builds at locations like: + +========== ========================================================================================================================== +Channel URL +========== ========================================================================================================================== +Release https://archive.mozilla.org/pub/firefox/candidates/88.0.1-candidates/build1/win64/en-US/firefox-88.0.1.zip +Beta https://archive.mozilla.org/pub/firefox/candidates/89.0b15-candidates/build1/win64/en-US/firefox-89.0b15.zip +Devedition https://archive.mozilla.org/pub/devedition/candidates/89.0b15-candidates/build1/win64/en-US/firefox-89.0b15.zip +Nightly https://archive.mozilla.org/pub/firefox/nightly/2021/05/2021-05-21-09-57-54-mozilla-central/firefox-90.0a1.en-US.win64.zip +========== ========================================================================================================================== + +Repackage using commands like: + +:: + + $ ./mach repackage msix \ + --input firefox-88.0.1.zip \ + --channel=official \ + --arch=x86_64 \ + --verbose + +Or package a local developer build directly with ``mach repackage msix``: + +:: + + $ ./mach repackage msix + +This command will do its best to guess your channel and other necessary +information. You can override these with options like ``--channel`` +(see the ``--help`` text for all supported options). + +Paths to tools can be set via environment variables. In order, searched +first to searched last: + +1. the tool name, like ``MAKEAPPX`` or ``SIGNTOOL`` +2. searching on ``PATH`` +3. searching under ``WINDOWSSDKDIR`` +4. searching under ``C:/Program Files (x86)/Windows Kits/10`` + +If you are cross compiling from Linux or macOS you will need a +compiled version of `Mozilla's fork of Microsoft's msix-packaging +<https://github.com/mozilla/msix-packaging/tree/johnmcpms/signing>`__ +tools. + +Linux users can obtain a prebuilt version with: + +:: + + $ ./mach artifact toolchain --from-build linux64-msix-packaging + +After `bug 1743036 <https://bugzilla.mozilla.org/show_bug.cgi?id=1743036>`__ +is fixed, macOS and Windows users will have a similar option. + +Signing locally +~~~~~~~~~~~~~~~ + +The repackaged MSIX files produced are not signed by default. In +automation, Mozilla's signing service signs the repackaged MSIX files. +For local testing, you can sign them with a self-signed certificate by +adding ``--sign`` to ``mach repackage msix``, or with commands like: + +:: + + $ ./mach repackage sign-msix --input test.msix --verbose + +Or sign them yourself following `Microsoft's self-signed certificate +instructions <https://docs.microsoft.com/en-us/windows/msix/package/create-certificate-package-signing#create-a-self-signed-certificate>`__. + +Signing Certificates +^^^^^^^^^^^^^^^^^^^^ + +Mach will create the necessary signing keys and certificates for you +and re-use them for subsequent signings. Before your locally signed +builds can be installed you will need to install the correct +certificate to the Windows Root Store. This can be done with a command +like: + +:: + + $ powershell -c 'Import-Certificate -FilePath mycert.cer -Cert Cert:\LocalMachine\Root\' + +The exact command to run will be shown if you run ``./mach repackage`` +with ``--verbose``. + +You _may_ choose to sign in a different manner, with a key and certificate +you create yourself, but Windows requires that the Subject of the certificate +match the Publisher found in the MSIX's AppxManifest.xml. If you choose +to go this route, ensure that you pass ``--publisher`` to +``./mach repackage msix`` to set that correctly. + +For developers +~~~~~~~~~~~~~~ + +Updating the MSIX template +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +MSIX is an "open format" in one sense: the MSIX container format is +specified at https://github.com/Microsoft/msix-packaging. It is +categorically *not* an open format in another sense: many of the +contained files are proprietary binary formats (``.reg`` -- registry +hive files) or undocumented (``.pri`` files -- resource index files). + +Generally the MSIX packaging code tries to avoid requiring such files +that can't be built from sources. Where they are truly required, it +tries to use a single such file independent of branding and other +configuration, checked into the source tree. + +resources.pri +''''''''''''' + +Generate a new ``resources.pri`` file on a Windows machine using +``makepri.exe`` from the Windows SDK, like: + +:: + + $ makepri.exe new \ + -IndexName firefox \ + -ConfigXml browser/installer/windows/msix/priconfig.xml \ + -ProjectRoot browser/branding/official/msix \ + -OutputFile browser/installer/windows/msix/resources.pri \ + -Overwrite + +The choice of channel (i.e., +``browser/branding/{official,aurora,beta,nightly,unofficial}``) should +not matter. + +.. [#] The MSI has to be limited in this way because of the difficulty + of migrating existing installations into MSI and adding support + for it to Firefox's update pipeline. MSIX does not have these + constraints, because the partially virtualized file system that + these kinds of apps run in makes install migration impossible + and unnecessary. |