... | ... | @@ -18,7 +18,7 @@ Current updates (on Linux 64-bit, en-US locale) use a URL like: |
|
|
When updating from a version of Tor Browser older than 8.0, due to the watershed the URL is something like:
|
|
|
- https://aus1.torproject.org/torbrowser/update_3/alpha/Linux_x86_64-gcc3/9.5a2/en-US
|
|
|
|
|
|
## Update Watersheds
|
|
|
# Update Watersheds
|
|
|
Over the years since Tor Browser began using automatic updates, the requirements of updating changed a few times. These changes were implemented by migrating to a new update location. These were watershed updates.
|
|
|
|
|
|
| Ticket | Path | Release |
|
... | ... | @@ -27,14 +27,14 @@ Over the years since Tor Browser began using automatic updates, the requirements |
|
|
| #26050 | update_3 | 8.0a10 |
|
|
|
| tor-browser-build#40678, #41414 | update_3 | 11.5.8 |
|
|
|
|
|
|
## History
|
|
|
# History
|
|
|
|
|
|
MAR files were signed beginning in 2014, with ticket #13379. Incremental mar files were implemented in #13324.
|
|
|
|
|
|
## Manually Applying MAR Update
|
|
|
# Manually Applying MAR Update
|
|
|
These instructions are based on https://wiki.mozilla.org/Software_Update:Manually_Installing_a_MAR_file
|
|
|
|
|
|
### Linux:
|
|
|
## Linux:
|
|
|
|
|
|
1. We assume the Tor Browser installation directory is `/path/to/torbrowser`, this is the directory normally named `tor-browser_${LOCALE}` (like `tor-browser_es-ES/` and it contains the `Browser/` directory)
|
|
|
1. Create a directory somewhere your user can read/write/execute, such as in your home directory (let's call it `app-update`).
|
... | ... | @@ -50,7 +50,7 @@ These instructions are based on https://wiki.mozilla.org/Software_Update:Manuall |
|
|
1. After this command is executed, an `update.status` file should be created in `app-update/`. If the update was applied successfully, then the file should contain "succeeded".
|
|
|
1. After successfully applying the update, simply delete the `app-update/` directory
|
|
|
|
|
|
### MacOS:
|
|
|
## MacOS:
|
|
|
1. Create a directory somewhere your use can read/write/execute, such as in your home directory (let's call it `app-update`).
|
|
|
1. Open `Applications` and open the context menu of `Tor Browser.app`, select "Show Package Contents`
|
|
|
1. After showing the package content, open `Contents/MacOS/` and copy `Tor Browser Software Update` (`updater.app`) into `app-update` (created above)
|
... | ... | @@ -63,7 +63,7 @@ These instructions are based on https://wiki.mozilla.org/Software_Update:Manuall |
|
|
1. After this command is executed, an `update.status` file should be created in `~/app-update/`. If the update was applied successfully, then the file should contain "succeeded".
|
|
|
1. After successfully applying the update, simply delete the `app-update/` directory
|
|
|
|
|
|
### Windows:
|
|
|
## Windows:
|
|
|
|
|
|
**NOTE**: These steps assume you installed Tor Browser in the default installation location: `%USERPROFILE%\Desktop\Tor Browser`. If you have installed Tor Browser somewhere else, you will need to update the commands referencing the Tor Browser installation directory to point to your custom installation path. Also note that `%USERPROFILE%` expands to the current user's home directory. For most users this is `C:\Users\%USERNAME%`.
|
|
|
|
... | ... | @@ -85,11 +85,11 @@ These instructions are based on https://wiki.mozilla.org/Software_Update:Manuall |
|
|
1. Cleanup the app-update directory
|
|
|
- `rmdir /S /Q %USERPROFILE%\app-update`
|
|
|
|
|
|
### MAR Troubleshooting
|
|
|
## MAR Troubleshooting
|
|
|
|
|
|
The provided updater program is not very user friendly and will not provide immediate user feedback in the event of failure. If the `update.status` file says anything besides "succeeded" you can examine the generated `updater.log` in your created `app-update` directory for clues. The most likely cause of error is using a MAR file that is not compatible with your Tor Browser installation. Unfortunately there are multiple ways in which you can use the wrong MAR file:
|
|
|
|
|
|
#### CPU an OS Architecture
|
|
|
### CPU an OS Architecture
|
|
|
|
|
|
First, you must be sure that the OS and and CPU architecture match between the MAR file and your Tor Browser installation:
|
|
|
|
... | ... | @@ -107,7 +107,7 @@ Just because you are running 64-bit Windows or Linux does not mean you need the |
|
|
|
|
|
The updater.log file will likely complain about mismatched file names if you use a MAR file for the wrong OS. It will likely complain about mismatched file sizes if you use a MAR file with the wrong CPU architecture.
|
|
|
|
|
|
#### Correct Incremental Version
|
|
|
### Correct Incremental Version
|
|
|
|
|
|
Second, if you are updating using an incremental MAR file (these MAR files end in `.incremental.MAR`) be sure that the 'from' version matches your Tor Browser installation's version. The incremental mar file's have a filename in the form: `tor-browser-$ARCH-$FROM_VERSION-$TO_VERSION_$LOCALE.incrementalmar`. For example, an incremental update from the American English 32-bit Windows Tor Browser version 9.5a6 to version 9.5a7 has the filename: `tor-browser-win32-9.5a6-9.5a7_en-US.incremental.mar`
|
|
|
|
... | ... | @@ -115,7 +115,7 @@ You can determine the version number by launching Tor Browser and looking at the |
|
|
|
|
|
The `updater.log` file will likely complain about mismatched file sizes if you use the wrong incremental version.
|
|
|
|
|
|
## Testing Updater
|
|
|
# Testing Updater
|
|
|
|
|
|
Testing the updater (and update process) is non-trivial. There are three separate modifications that must be made within the Tor Browser build environment.
|
|
|
|
... | ... | @@ -125,11 +125,11 @@ Testing the updater (and update process) is non-trivial. There are three separat |
|
|
|
|
|
In addition, you must [create a new public key pair](https://gitlab.torproject.org/tpo/applications/tor-browser-spec/-/blob/main/processes/KeyGeneration#L41) for signing mar files. Copy the resulting public certificate `marsigner.der` for later use, too.
|
|
|
|
|
|
### Updater URL
|
|
|
## Updater URL
|
|
|
|
|
|
Testing the `nightly` channel is easiest. The URL can be modified in the [build](https://gitlab.torproject.org/tpo/applications/tor-browser-build/-/blob/main/projects/firefox/build#L105) script. If you are testing `release` or `alpha` then a more complicated patch will be needed.
|
|
|
|
|
|
### Signature Public Certificate
|
|
|
## Signature Public Certificate
|
|
|
|
|
|
After creating the new testing key pair, add the new certificate into tor-browser by overwriting the appropriate secondary key. For `nightly`, you can achieve this with a patch
|
|
|
```patch
|
... | ... | @@ -160,30 +160,20 @@ index 006c3c9d7c68..fa59b712776e 100644 |
|
|
+ - filename: marsigner.der
|
|
|
```
|
|
|
|
|
|
### Import Public Certificate
|
|
|
## Sign MAR file
|
|
|
|
|
|
```sh
|
|
|
nssdb="/path/to/nssdb"
|
|
|
mkdir $nssdb
|
|
|
mar_tools="path/to/mar-tools"
|
|
|
pubkey="/path/to/marsigner.der"
|
|
|
$mar_tools/certutil -A -n marsigner -d $nssdb -t ,, -i $pubkey
|
|
|
```
|
|
|
|
|
|
### Sign MAR file
|
|
|
|
|
|
```sh
|
|
|
mar_tools="path/to/mar-tools"
|
|
|
nssdb="/path/to/nssdb_public"
|
|
|
nssdb="/path/to/nssdb"
|
|
|
marfile="/path/to/tor-browser-linux64-testbuild1_en-US.mar"
|
|
|
mkdir signed
|
|
|
|
|
|
$mar_tools/signmar -d $nssdb -n marsigner -s $marfile signed/$marfile
|
|
|
```
|
|
|
|
|
|
### Verify Signed MAR file
|
|
|
## Verify Signed MAR file
|
|
|
|
|
|
1. Using the same database containing the private key material
|
|
|
### Using the same database containing the private key material
|
|
|
|
|
|
```sh
|
|
|
mar_tools="path/to/mar-tools"
|
... | ... | @@ -194,7 +184,19 @@ mkdir signed |
|
|
$mar_tools/signmar -d $nssdb -n marsigner -v signed/$marfile
|
|
|
```
|
|
|
|
|
|
2. Using a separate database with only the public certificate
|
|
|
### Using a separate database with only the public certificate
|
|
|
|
|
|
#### Create a new database with the public certificate
|
|
|
|
|
|
```sh
|
|
|
nssdb="/path/to/nssdb"
|
|
|
mkdir $nssdb
|
|
|
mar_tools="path/to/mar-tools"
|
|
|
pubkey="/path/to/marsigner.der"
|
|
|
$mar_tools/certutil -A -n marsigner -d $nssdb -t ,, -i $pubkey
|
|
|
```
|
|
|
|
|
|
#### Verify the signature
|
|
|
|
|
|
```sh
|
|
|
mar_tools="path/to/mar-tools"
|
... | ... | |