=====================
Firefox Update Hotfix
=====================

This directory contains a hotfix to upgrade old (stuck) Firefox
clients to new versions using a full installer (as opposed to the
upgrade mechanism built into Firefox).

Security of Installers
======================

The hotfix downloads a Firefox installer from a remote server over
HTTP (as opposed to HTTPS). Not using TLS may seem inappropriate, but
it is a deliberate choice.

First, we don't need TLS for security of the download. Downloaded
installers have their SHA-512 hashes verified against the hashes that
ship with this hotfix. Those hashes are obtained from a Mozilla
server and the file containing the list of hashes has its GPG
signature verified as part of obtaining the hashes via
``import-installers.py``. If the hash of the downloaded file
doesn't match what we expect, the client will discard the download.

TLS also introduces points of failure where the download could fail.
For example, many corporate networks employ MITM proxies that sniff
SSL traffic. These corporate setups may have opted to install the
certificate of the MITM proxy in e.g. Internet Explorer but not
Firefox. Firefox may thus fail certificate verification and refuse to
download an installer.

TLS is also sensitive to clock accuracy. We know many machines don't
have accurate system clocks. This could cause TLS to fail.

Avoiding TLS eliminates the potential for TLS to fail.

Avoiding TLS does have one drawback: client privacy. Without TLS,
parties with access to the network traffic will see a client
downloading a Firefox installer. However, this privacy benefit is
tenuous. Most network setups will likely be using traditional DNS.
Observers will see a DNS request to Mozilla's download hostname
followed by a multi-megabyte TCP stream. It would be obvious what's
going on there, even with TLS.

In the case of installer downloading, TLS provides little to not
benefit while introducing real risk. We have decided to not use TLS
for downloading.

Importing Upgrade Targets
=========================

The upgrade targets (the set of installers) is fetched from Mozilla's
servers using the ``import-installers.py`` script.

This script performs cryptographic signature checking. This requires
some Python libraries. You'll want to create a virtualenv to hold
the new Python packages so you don't pollute your system's Python
install::

  $ virtualenv venv
  $ source venv/bin/activate
  $ pip install gnupg which

Then, run ``import-installers.py`` to produce a JSON file of target
installers::

  $ import-installers.py http://download-installer.cdn.mozilla.net/pub/firefox/releases/29.0.1

Test Plan
=========

Expected Behavior
-----------------

The following behavior of the hotfix should be verified:

1. When the hotfix is installed on a qualifying client, a download
   begins automatically in the background.

   a. If Firefox is restarted mid-download, the download should resume
      where it left off automatically. This can be verified by looking
      at logs.

2. When the installer has finished downloading, its contents are verified.
   a. If the size of the installer on disk does not match what is expected
      in the installers.json file, the installer is deleted from disk
      and a new download begins. The new download won't occur until a
      timer fires a few minutes later or until a restart.

      You can verify this by changing the size of the ``.exe.part`` file
      between Firefox restarts mid-download.

   b. If the hash of the downloaded file does not match what is defined
      in installers.json, the installer is deleted from disk and a new
      download begins (again after a timer or restart).

      You can verify this by changing a byte in the ``.exe.part`` file
      between Firefox restarts mid-download.

3. When Firefox starts up and an installer has been previously downloaded,
   that installer is verified for size and hash. If the size and hash do
   not match what is in ``installers.json``, the installer is removed and
   a new download begins immediately.

   You can verify this by changing the size and content of a downloaded
   file after successful download.

4. The first time an installer has been downloaded and verified, we will
   attempt to run that installer automatically without any prompting or
   notification within Firefox.

5. When we attempt to run the installer, we will correctly handle
   permissions issues.

   a. For users on Windows XP that have write access to the installation
      directory, there should be no OS-level UAC or privilege escalation
      prompts.

   b. For users on Windows XP that don't have write access
      to the installation directory, we don't attempt an install and
      abort. (This scenario should be rare.)

   c. For regular users on Windows 7 with default UAC settings, a UAC
      prompt will likely appear. If elevation is allowed, the installer
      should run. If elevation is not allowed or fails (perhaps due to
      inputting the wrong password), we don't run the installer and
      record a *transient* failure.

   d. For adminstrator users on Windows 7 with default UAC settings, a
      UAC prompt will likely appear. See above.

6. If the installer fails to work due to a problem with the installer,
   the hotfix should uninstall itself.

   Note that UAC or permissions failures are not grounds for immediate
   uninstall.

   TODO how to test this?

7. If an install has previously been attempted but didn't finish, the
   user should see a notification on about:home when the browser starts.

   a. If about:home is the default homepage, the notification should
      appear on the single homepage tab
   b. If about:home is not the default homepage, an about:home tab
      is opened, given focus, and the notification is shown there.

8. The notification should control subsequent actions.

   a. The notification should have UI consistent with similar
      notifications, such as the plugin doorhanger.

   b. There should be a dropdown saying *Start using it now* with
      *Not now* as an alternate selection.

   c. The notification should be translated to the locales shipped
      with this hotfix. en-US should be used if a translation is not
      available.

   d. Clicking *Start using it now* in the notification should result
      in an install attempt. See #5. The notification should be removed
      on click.

   e. Clicking *Not now* should result in the dismissal of the
      notification and no install attempt.

   f. Clicking outside the notification should result in the
      notification going away. No install should be attempted.

   g. Hotkeys inside the notification work.

9. The notification should appear at most once per day and have
   expected messaging.

   a. The notification should appear on startup no more than once per
      day. A day transitions at 4 AM local time. It is possible to
      see the notification at 3:59 AM and again at 4:00 AM.

   b. The default *ready_full* message is displayed on the first 7
      days of notifications.

   c. The *ready_alt1* and *ready_alt2* messages are shown in random
      order starting 7 days after the first notification is seen.

      You can verify this by adjusting the ``firstNotifyDay`` and
      ``lastNotifyDay`` preferences or by adjusting the system clock.
      System clock is preferred.

10. Upon successful installer execution, Firefox 30 should run after
    restart.

   a. A system reboot should not be required to finish installation.

11. The locale of the install should be preserved after upgrade.

   a. If upgrading from ``es-ES``, you should install an ``es-ES``
      build.

12. The hotfix should uninstall itself after first launch after
    a successful install.

13. Hotfix uninstall should remove most traces.

   a. The ``hotfix-update`` directory under the profile directory
      should be completely removed.

   b. The ``hotfix.v20140527.01`` pref branch should not be present.

   c. The ``hotfix.v20140527.01.json`` file **should** exist in the
      main profile directory.

14. The hotfix should not introduce considerable jank or performance
    issues.

   a. Please test the hotfix on old, slow hardware and report
      results. Report fresh reboot results for best results.

   b. The hotfix does not assign a low priority to the installer
      download. This is by design to help ensure a completed
      download. Impact on surfing bandwidth during download is
      expected.

15. The user should be able to uninstall the hotfix via about:addons.
    Everything that happens during regular uninstall should happen
    with this method as well.

16. The hotfix will immediately uninstall itself unless all
    qualifications are met.

    a. The operating system must be Windows.
    b. The Firefox build must be 32-bit.
    c. The Windows version is Windows XP SP2 or newer.
    d. It isn't a partner build.
    e. The update channel must be ``release``.
    f. Automatic application updates must be enabled.
    g. We are running Firefox 29 or older.
    h. We are able to determine the locale of the existing
       installation.
    i. We have an installer for the build and locale from
       installers.json.

17. If the installer fails due to no fault of the user (e.g. permissions
    problems), the browser should open a new tab to SUMO.

    a. The page should be something like
       https://support.mozilla.org/en-US/kb/firefox-failed-update-how-update-manually

What to Test
------------

It is important that successful installs and important functionality
such as downloading resuming and notifications be tested on Firefox
10.0 through 28.0. Every released major version needs to be tested,
as any single version could introduce subtle API breakage that may
need workarounds. We also need to test every version on Windows XP
and Windows 7. Windows 8 testing only needs to be performed on the
Firefox versions that officially support Windows 8.

We need explicit coverage to verify the hotfix uninstalls itself
when it should. This includes testing on:

* Firefox 9
* Linux and OS X builds
* A 64-bit Windows build
* Windows XP XP1 or Windows XP w/o a service pack
* At least 2 partner builds
* A build on the Beta and Aurora channels
* A build with auto updates disabled
* Firefox 30.0

We also need one-off tests for:

* Locale notification usage and preservation after upgrade
* Running Firefox in Firefox safe mode
* Running Windows in safe mode on Windows XP and 7
* Upgrading Firefox installed in a non-default location (such as your
  user directory)
* Upgrading Firefox as a non-adminstrator
* Making the installer fail (somehow) so we can verify that is handled
  properly.
* Firefox in offline mode