Tb auto updates

boklm, rgdd (2026-03-14) -- breakout

topic: broad strokes, how does tor browser auto updates work?

TB has a public key embedded.

The corresponding private key is controlled by the TB team, stored on an offline-only computer.

Periodically, TB asks an HTTPS endpoint telling the running version "hey is there a new update".

If yes: the manifest contains links to a full "mar" file and optionaly an incremental one.

https://wiki.mozilla.org/Software_Update:MAR

  • In the case of an incremental mar file, a binary diff to apply to your existing TB files (configuration, few binaries, few libraries)
  • Or if your TB is old and there is no diff file from version X to Y, you will get a full mar file, containing new files to basically replace old TB with new TB.

The updater downloads the mar file and verify the signature before applying it.

Apply, then done!

Every release of TB is reproducible (checkout corresponding git tags to rebuild).

The manifest that contains information about the diff to apply (checksums and such) is also reproducible from git source.

The signature is created using signmar, tooling by mozilla. Then corresponding signature verify stuff that's in firefox is used to verify the signature.

A detail: if user is on version X.1; X.2 contains an incompatible change (e.g. pubkey changes); and latest version is X.3; then we can force autoupdate to go through X.2 and then up to X.3. I.e., when doing the HTTPS request to check for a new update, the updater will be sure to go through the version that changed the embedded pubkey so things keep working.

After going through this, we talked about how it would be relatively easy to add translogging (e.g., sigsum) to this setup.

Basically sign using sigsum-submit (which supports signing offline and getting the proof 'online' separately). Mostly just need to get sigsum-submit onto the offline machine and then once getting the signature out, submit it to a log.

And in the mozilla verify library code, support verifying sigsum's transparent signature based on a submit key, log key(s), and witness key(s) that would be hardcoded in TB. I.e., this is the same as before, just that instead of a single TB pubkey it's a TB submit key + log keys + witness keys + how many witness cosignatures are needed in order to consider the update transparent.

(At first, this would have to be an out-of-tree patch that TB team applies, and maybe it could be upstream:ed if Mozilla sees the value in supporting it. But it is not a major concern to have an out-of-tree patch, it's one of several.)

The updater code that needs to be updated is probably this:

The monitor in this translog system would do two things:

  • Reprobuild all TB tags / diffs, scream if something is wrong (this is the status quo, and doesn't depend on translogging at all).
  • For each signed checksum in a sigsum log, doublecheck that the monitor reprobuilt correctly for the corresponding checksum. If not, we just detected a hidden release and/or a release that doesn't build reproducibly.

To get a feel for sigsum's current tooling, see: