Updating.md

@@ -84,11 +84,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:
 
@@ -106,10 +106,73 @@ 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`
 
 You can determine the version number by launching Tor Browser and looking at the top-right hand corner of `about:tor` (for left-to-right languages). The version can also be found in the `About Tor` dialog as described in the previous section.
 
 The `updater.log` file will likely complain about mismatched file sizes if you use the wrong incremental version.
+
+## 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.
+
+1. Update URL
+1. Signature public key
+1. Nightly build configuration file
+
+In addition, you must [create a new public key pair](https://gitlab.torproject.org/tpo/applications/tor-browser-spec/-/blob/master/processes/KeyGeneration#L41) for signing mar files. Copy the resulting public certificate  `marsigner.der` for later use, too.
+
+### 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/master/projects/firefox/build#L105) script. If you are testing `release` or `alpha` then a more complicated patch will be needed.
+
+### 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
+
+### Import 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
+```
+
+### Sign MAR file
+
+```sh
+mar_tools="path/to/mar-tools"
+nssdb="/path/to/nssdb_public"
+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
+
+1. Using the same database containing the private key material
+
+```sh
+mar_tools="path/to/mar-tools"
+nssdb="/path/to/nssdb"
+marfile="/path/to/tor-browser-linux64-testbuild1_en-US.mar"
+mkdir signed
+
+$mar_tools/signmar -d $nssdb -n marsigner -v signed/$marfile
+```
+
+2. Using a separate database with only the public certificate
+
+```sh
+mar_tools="path/to/mar-tools"
+nssdb="/path/to/nssdb_public"
+marfile="/path/to/tor-browser-linux64-testbuild1_en-US.mar"
+mkdir signed
+
+$mar_tools/signmar -d $nssdb -n marsigner -v signed/$marfile
+```