MSIX.rst (9981B)
1 MSIX Package 2 ============ 3 4 Firefox MSIX packages are full participants in the "modern" Windows 5 app packaging system. They are distributed, installed, updated, 6 repaired, and uninstalled entirely using that system. This gives 7 administrators lots of deployment options, and also grants complete 8 control over when and how application updates are rolled out 9 (Firefox's built-in updater is always fully disabled in MSIX 10 packages). This stands in contrast to Firefox MSI packages, which 11 mostly work against the Windows Installer framework rather than with 12 it, and therefore are missing a lot of important functionality; for 13 example, tools that install MSI packages generally cannot uninstall 14 Firefox [#]_. This means the MSIX package may well be the better 15 option for deploying to Windows 10 and up. 16 17 In automation 18 ------------- 19 20 The ``repackage-msix`` and ``repackage-shippable-l10n-msix`` tasks 21 repackage the ZIP packages produced by signed build tasks into MSIX 22 packages. The ``shippable-l10n`` variants depend on Linux64 builds and 23 localization tasks to produce signed langpacks, which are incorporated 24 into the MSIX package as distribution extensions. (This is the same 25 approach taken by ``snap`` and ``flatpak`` Linux packages.) 26 27 The ``repackage-signing-msix`` and 28 ``repackage-signing-shippable-l10n-msix`` tasks sign the MSIX packages 29 produced by the repackage tasks. 30 31 Signing in automation 32 ~~~~~~~~~~~~~~~~~~~~~ 33 34 MSIX packages are signed by the same certificates that sign binaries for 35 other jobs. In practice, this means that try builds are signed with the 36 ```Mozilla Fake CA`` 37 certificate `MozFakeCA_2017-10-13.cer <https://raw.githubusercontent.com/mozilla-releng/OpenCloudConfig/3493a608bf700b68a54ff2fd506f33373bb87a04/userdata/Configuration/Mozilla%20Maintenance%20Service/MozFakeCA_2017-10-13.cer>`__. 38 In order to install try builds locally, you must trust this certificate. 39 **For your own security, it's best to do this in Windows Sandbox or a 40 Virtual Machine**. To do so run the following in an elevated 41 (administrator) Powershell: 42 43 :: 44 45 $ Import-Certificate -FilePath "MozFakeCA_2017-10-13.cer" -Cert Cert:\LocalMachine\Root\ 46 ... 47 Thumbprint Subject 48 ---------- ------- 49 FA056CEBEFF3B1D0500A1FB37C2BD2F9CE4FB5D8 CN=Mozilla Fake CA 50 51 The ``shippable-l10n`` MSIX variants incorporate signed langpacks. These 52 in turn are signed with the same certificate. Firefox knows about this 53 certificate but does not trust it by default. To trust it, set the 54 hidden Gecko boolean preference 55 56 :: 57 58 xpinstall.signatures.dev-root=true 59 60 Sadly, it's not possible to set preferences via a ``distribution.ini`` 61 early enough to impact loading the signed langpacks (see `Bug 62 1721764 <https://bugzilla.mozilla.org/show_bug.cgi?id=1721764>`__), and 63 once the signed langpacks fail to load once, they will not be reloaded 64 (see `Bug 65 1721763 <https://bugzilla.mozilla.org/show_bug.cgi?id=1721763>`__). This 66 make testing the first-run experience challenging. What can be done is 67 to install the MSIX package (perhaps using 68 ``Add-AppxPackage -Path ...``) and determine the profile directory 69 (using ``about:support``). Uninstall the MSIX package (perhaps using 70 ``Get-AppxPackage | Where -Property Name -like "Mozilla.*" | Remove-AppxPackage``). 71 Delete the contents of the profile directory entirely, but add a file 72 ``user.js`` containing: 73 74 :: 75 76 user_pref("xpinstall.signatures.dev-root", true); 77 user_pref("extensions.logging.enabled", true); 78 79 Reinstall the MSIX package and the signed langpacks should now be loaded 80 (slowly!) and available after first startup. 81 82 Local developer builds 83 ---------------------- 84 85 ``mach repackage msix`` lets you repackage a Firefox package (or 86 directory) into an MSIX/App Package. The main complication is that an 87 App Package contains channel-specific paths and assets, and therefore 88 needs to be branding-aware, much as an Android package needs to be 89 branding-aware. 90 91 Usage 92 ~~~~~ 93 94 The tool is designed to repackage ZIP archives produced in automation. 95 Start looking for official builds at locations like: 96 97 ========== ========================================================================================================================== 98 Channel URL 99 ========== ========================================================================================================================== 100 Release https://archive.mozilla.org/pub/firefox/candidates/88.0.1-candidates/build1/win64/en-US/firefox-88.0.1.zip 101 Beta https://archive.mozilla.org/pub/firefox/candidates/89.0b15-candidates/build1/win64/en-US/firefox-89.0b15.zip 102 Devedition https://archive.mozilla.org/pub/devedition/candidates/89.0b15-candidates/build1/win64/en-US/firefox-89.0b15.zip 103 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 104 ========== ========================================================================================================================== 105 106 Repackage using commands like: 107 108 :: 109 110 $ ./mach repackage msix \ 111 --input firefox-88.0.1.zip \ 112 --channel=official \ 113 --arch=x86_64 \ 114 --verbose 115 116 Or package a local developer build directly with ``mach repackage msix``: 117 118 :: 119 120 $ ./mach repackage msix 121 122 This command will do its best to guess your channel and other necessary 123 information. You can override these with options like ``--channel`` 124 (see the ``--help`` text for all supported options). 125 126 Paths to tools can be set via environment variables. In order, searched 127 first to searched last: 128 129 1. the tool name, like ``MAKEAPPX`` or ``SIGNTOOL`` 130 2. searching on ``PATH`` 131 3. searching under ``WINDOWSSDKDIR`` 132 4. searching under ``C:/Program Files (x86)/Windows Kits/10`` 133 134 If you are cross compiling from Linux or macOS you will need a 135 compiled version of `Mozilla's fork of Microsoft's msix-packaging 136 <https://github.com/mozilla/msix-packaging/tree/johnmcpms/signing>`__ 137 tools. 138 139 Linux users can obtain a prebuilt version with: 140 141 :: 142 143 $ ./mach artifact toolchain --from-build linux64-msix-packaging 144 145 After `bug 1743036 <https://bugzilla.mozilla.org/show_bug.cgi?id=1743036>`__ 146 is fixed, macOS and Windows users will have a similar option. 147 148 Avoiding signing locally with unsigned packages 149 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 150 151 Windows 11 allows to install unsigned packages, provided that its AppX 152 manifest includes a special OID (organization ID) value in its 153 ``Identity`` element. See 154 https://github.com/MicrosoftDocs/msix-docs/blob/769dee9364df2b6fd0b78000774f8d14de8fe814/msix-src/package/unsigned-package.md. 155 To produce a suitable package, use the ``--unsigned`` command line 156 switch, like: 157 158 :: 159 160 $ ./mach repackage msix --unsigned 161 162 Note that unsigned packages **must** be installed by an administrator. 163 Generally, run Powershell as an administrator and then use commands like 164 165 :: 166 167 $ Add-AppxPackage -Path ... -AllowUnsigned -ForceUpdateFromAnyVersion 168 169 Signing locally 170 ~~~~~~~~~~~~~~~ 171 172 The repackaged MSIX files produced are not signed by default. In 173 automation, Mozilla's signing service signs the repackaged MSIX files. 174 For local testing, you can sign them with a self-signed certificate by 175 adding ``--sign`` to ``mach repackage msix``, or with commands like: 176 177 :: 178 179 $ ./mach repackage sign-msix --input test.msix --verbose 180 181 Or sign them yourself following `Microsoft's self-signed certificate 182 instructions <https://docs.microsoft.com/en-us/windows/msix/package/create-certificate-package-signing#create-a-self-signed-certificate>`__. 183 184 Signing Certificates 185 ^^^^^^^^^^^^^^^^^^^^ 186 187 Mach will create the necessary signing keys and certificates for you 188 and reuse them for subsequent signings. Before your locally signed 189 builds can be installed you will need to install the correct 190 certificate to the Windows Root Store. This can be done with a command 191 like: 192 193 :: 194 195 $ powershell -c 'Import-Certificate -FilePath mycert.cer -Cert Cert:\LocalMachine\Root\' 196 197 The exact command to run will be shown if you run ``./mach repackage`` 198 with ``--verbose``. 199 200 You _may_ choose to sign in a different manner, with a key and certificate 201 you create yourself, but Windows requires that the Subject of the certificate 202 match the Publisher found in the MSIX's AppxManifest.xml. If you choose 203 to go this route, ensure that you pass ``--publisher`` to 204 ``./mach repackage msix`` to set that correctly. 205 206 For developers 207 ~~~~~~~~~~~~~~ 208 209 Updating the MSIX template 210 ^^^^^^^^^^^^^^^^^^^^^^^^^^ 211 212 MSIX is an "open format" in one sense: the MSIX container format is 213 specified at https://github.com/Microsoft/msix-packaging. It is 214 categorically *not* an open format in another sense: many of the 215 contained files are proprietary binary formats (``.reg`` -- registry 216 hive files) or undocumented (``.pri`` files -- resource index files). 217 218 Generally the MSIX packaging code tries to avoid requiring such files 219 that can't be built from sources. Where they are truly required, it 220 tries to use a single such file independent of branding and other 221 configuration, checked into the source tree. 222 223 resources.pri 224 ''''''''''''' 225 226 Generate a new ``resources.pri`` file on a Windows machine using 227 ``makepri.exe`` from the Windows SDK, like: 228 229 :: 230 231 $ makepri.exe new \ 232 -IndexName firefox \ 233 -ConfigXml browser/installer/windows/msix/priconfig.xml \ 234 -ProjectRoot browser/branding/official/msix \ 235 -OutputFile browser/installer/windows/msix/resources.pri \ 236 -Overwrite 237 238 The choice of channel (i.e., 239 ``browser/branding/{official,aurora,beta,nightly,unofficial}``) should 240 not matter. 241 242 .. [#] The MSI has to be limited in this way because of the difficulty 243 of migrating existing installations into MSI and adding support 244 for it to Firefox's update pipeline. MSIX does not have these 245 constraints, because the partially virtualized file system that 246 these kinds of apps run in makes install migration impossible 247 and unnecessary.