|
|
|
|
|
[[_TOC_]]
|
|
|
|
|
|
# The Tor Browser Hacking Guide
|
|
|
|
|
|
Welcome to the Official Tor Browser Hacking Guide. This page is meant to give you an overview of how to get started with Tor Browser development.
|
|
|
|
|
|
This page covers building the browser, debugging the browser, how we communicate and use Gitlab to organize our issues and development process, what goes into the browser itself, and also provides links to other development resources and information.
|
|
|
|
|
|
# Ways to Build Tor Browser
|
|
|
|
|
|
The first thing you probably want to know is how to obtain the very latest (and sometimes greatest) Tor Browser builds, and how to build your own version of the Tor Browser from our source code. Well wait no further.
|
|
|
|
|
|
## Nightly Builds
|
|
|
|
|
|
See [this page](Nightly-Builds-Download) for information about downloading nightly builds.
|
|
|
|
|
|
As with all of our builds, it should be possible to reproduce byte-for-byte identical versions of all of those binaries from source. To learn how to do that, read on.
|
|
|
|
|
|
## Building Official Tor Browser Release Binaries
|
|
|
|
|
|
Our build system is based on [rbm](https://gitlab.torproject.org/tpo/applications/rbm/), which is developed by boklm. rbm creates containers using `user_namespaces` to provide a clean, controlled, reproducible build environment in a fully automated fashion. We further wrap rbm with our own helper scripts that download and authenticate inputs, and automate building and assembling each component piece of the browser into a final set of output packages for Linux, MacOS, Windows, and Android. This is done with code in the [tor-browser-build repository](https://gitlab.torproject.org/tpo/applications/tor-browser-build/).
|
|
|
|
|
|
This system enables us to provide secure, verifiable, byte-for-byte reproducible builds to ensure the integrity of our binaries and to protect the build process from compromise. We have written a pair of blog posts that describe in more detail [why this is important](https://blog.torproject.org/blog/deterministic-builds-part-one-cyberwar-and-global-compromise), and the [technical details](https://blog.torproject.org/blog/deterministic-builds-part-two-technical-details) behind how this previously got achieved when using the [Gitian system](https://gitian.org/), if you are curious. The new build system based on rbm is working similarly and is facing pretty much the same issues.
|
|
|
|
|
|
To build the Tor Browser, you need essentially a relatively recent x86_64 Linux system. Check out a copy of the tor-browser-build repo with:
|
|
|
```
|
|
|
git clone https://gitlab.torproject.org/tpo/applications/tor-browser-build.git
|
|
|
cd tor-browser-build
|
|
|
```
|
|
|
|
|
|
After that you most likely need to install the additional dependencies [mentioned in the README file](https://gitlab.torproject.org/tpo/applications/tor-browser-build/-/blob/master/README). After installing any remaining dependencies, you should be able to run `make`, `make alpha`, `make nightly`, or `make testbuild` to build the entire bundle for all four platforms. The build scripts will detect any additional packages or configuration you need to perform on your system.
|
|
|
|
|
|
You will also find a [BUILD_ERRORS.txt file](https://gitlab.torproject.org/tpo/applications/tor-browser-build/-/blob/master/doc/BUILD_ERRORS.txt) under `doc/` with further information, should you run into any issues.
|
|
|
|
|
|
## Reproducing an Existing Build
|
|
|
The Tor Browser build process is using signed tags for official builds. Stable tags follow the scheme `tbb-X.X.X-buildN` where `X` are figures building the version number (like `7.5`) and `buildN` specifies the build number for this particular browser version (e.g. `build3`). Tags for the alpha releases are similar but contain an `a` in it like `tbb-8.0a1-build3`.
|
|
|
|
|
|
Once you know which version you want to reproduce check out the tag containing the latest build number and start doing a `make` if it is a stable version or `make alpha` if it is part of the alpha series.
|
|
|
|
|
|
At the end of the build you should end up with a `sha256sums-unsigned-build.txt` file containing all the SHA-256 sums of the bundles and related packages in `alpha/unsigned/your-tor-browser-version` (or `release/unsigned/your-tor-browser-version`, respectively). They should match the official hash sums we have produced.
|
|
|
|
|
|
Be aware that this process is not fully future-proof. In particular, if Debian has updated their development tool chain since the bundles have been built, you may encounter differences between your resulting bundles and the original binaries. This should be rare, however, as we use only the "Long Term Support" or "Oldstable" of Debian in our build VMs. The only reason they should change the tool chain is in the event of serious security issues in the development tools themselves.
|
|
|
|
|
|
## Partial Builds
|
|
|
|
|
|
This section is mostly of interest to developers making changes to Tor Browser or its components, and who wish to test their patches.
|
|
|
|
|
|
### Building Just Firefox
|
|
|
|
|
|
If you want to just develop on the browser without messing with rbm (for example, to have incremental rebuilds of just the files you modify), the best way is to build a new browser distribution and copy the result over an existing Tor Browser directory.
|
|
|
|
|
|
Clone the [Tor Browser repo](https://gitlab.torproject.org/tpo/applications/tor-browser):
|
|
|
|
|
|
```
|
|
|
git clone https://gitlab.torproject.org/tpo/applications/tor-browser.git
|
|
|
cd tor-browser
|
|
|
```
|
|
|
|
|
|
To build it on a Linux x86_64 machine, from the top directory of the `tor-browser` repo, do:
|
|
|
|
|
|
1. Install the required dependencies:
|
|
|
- [Common dependencies](https://gitlab.torproject.org/tpo/applications/tor-browser-build/-/blob/43033abc8a89da9012c385dbb415ce1c971d6959/projects/firefox/config#L16)
|
|
|
- [Linux x86_64 Dependencies](https://gitlab.torproject.org/tpo/applications/tor-browser-build/-/blob/43033abc8a89da9012c385dbb415ce1c971d6959/projects/firefox/config#L61)
|
|
|
|
|
|
```
|
|
|
# Include the source of tor-launcher to the browser/extensions repository.
|
|
|
git clone https://gitlab.torproject.org/tpo/applications/tor-launcher.git
|
|
|
mv tor-launcher browser/extensions/
|
|
|
|
|
|
# Clone/checkout the torbutton submodule
|
|
|
git submodule update --init
|
|
|
|
|
|
# Generate the configure scripts:
|
|
|
./mach configure --with-tor-browser-version=tbb-nightly --with-distribution-id=org.torproject --enable-update-channel=default --enable-bundled-fonts --with-branding=browser/branding/nightly
|
|
|
|
|
|
# And... compile and package:
|
|
|
./mach build
|
|
|
./mach build stage-package
|
|
|
|
|
|
# Point the INSTDIR at an existing TBB directory:
|
|
|
export INSTDIR="$HOME/tbb/test/tor-browser_en-US"
|
|
|
|
|
|
# Move the compiled firefox on top of the old TBB browser dir:
|
|
|
cp $INSTDIR/Browser/firefox $INSTDIR/Browser/start-firefox
|
|
|
cp -a obj-*/dist/firefox/* $INSTDIR/Browser/
|
|
|
rm $INSTDIR/Browser/firefox-bin
|
|
|
rm -f $INSTDIR/Browser/*.chk
|
|
|
cp $INSTDIR/Browser/firefox $INSTDIR/Browser/firefox.real
|
|
|
cp $INSTDIR/Browser/start-firefox $INSTDIR/Browser/firefox
|
|
|
|
|
|
# If you want a smaller binary to copy into a vm/other machine for tests:
|
|
|
strip --strip-all $INSTDIR/Browser/*
|
|
|
rm -f $INSTDIR/Browser/firefox-bin
|
|
|
```
|
|
|
|
|
|
If that completes successfully, then your fresh build of Firefox should exist at `$INSTDIR/Browser/firefox`. Free the lizard.
|
|
|
|
|
|
### Modifying Tor Launcher or Torbutton
|
|
|
|
|
|
Building tor-launcher and torbutton alone are not support anymore. Modify the files in-tree.
|
|
|
|
|
|
# Building Android Tor Browser
|
|
|
|
|
|
Android Tor Browser involves a more challenging development process than Tor Browser for desktop platforms (Windows, macOS, Linux).
|
|
|
|
|
|
## Android Tor Browser
|
|
|
|
|
|
Android Tor Browser is based on [Mozilla Fenix](https://github.com/mozilla-mobile/fenix). It's architecture is more modular than desktop Firefox and the previous version of Android Firefox (`Fennec`).
|
|
|
|
|
|
Android Tor Browser is composed of five main components:
|
|
|
- `fenix`
|
|
|
- `android-components`
|
|
|
- `application-services`
|
|
|
- `glean`
|
|
|
- `geckoview`
|
|
|
|
|
|
These components fit together in a mostly layered way:
|
|
|
|
|
|
#### Fenix
|
|
|
|
|
|
[Fenix](https://github.com/mozilla-mobile/fenix) is the repository that *is* the Firefox app. It provides most of the UI for the app and it glues most of the other pieces together.
|
|
|
|
|
|
#### Android Components
|
|
|
|
|
|
[Android Components](https://github.com/mozilla-mobile/android-components) is, as the name implies, a collection of components for Android. It's goal is providing all of the building blocks in a developer-friendly way that can be used to build web technology - including a web browser.
|
|
|
|
|
|
#### Application Services
|
|
|
|
|
|
[Application Services](https://github.com/mozilla/application-services) provides a suite of Mozilla services integration.
|
|
|
|
|
|
#### Glean
|
|
|
|
|
|
[Glean](https://github.com/mozilla/glean) provides a telemetry collection and reporting service.
|
|
|
|
|
|
#### Geckoview
|
|
|
|
|
|
[Geckoview](https://mozilla.github.io/geckoview/) is the heart of the browser. It provides gecko, Mozilla's browser engine, and a (relatively) thin wrapper API for interacting with it and similar to the [webview](https://developer.android.com/reference/android/webkit/WebView) API. See also the [Build web apps in WebView ](https://developer.android.com/guide/webapps/webview) guide for some more context.
|
|
|
|
|
|
### Setup
|
|
|
|
|
|
#### General
|
|
|
|
|
|
We modify three out of five repositories. Clone each of them:
|
|
|
- `git clone https://gitlab.torproject.org/tpo/applications/fenix.git`
|
|
|
- `git clone https://gitlab.torproject.org/tpo/applications/android-components.git`
|
|
|
- (if needed) `git clone https://gitlab.torproject.org/tpo/applications/tor-browser.git`
|
|
|
|
|
|
Note: We use the Tor Browser repository for geckoview, as well.
|
|
|
|
|
|
#### Geckoview
|
|
|
|
|
|
Find the branch you want to build. We'll assume you'll build the current Nightly (Alpha) branch. To find the correct branch name, we refer to `tor-browser-build` because that holds the authoritative definition of the branch. At the time of writing, the top of the `projects/geckoview/config` file looks like:
|
|
|
|
|
|
```
|
|
|
# vim: filetype=yaml sw=2
|
|
|
version: '[% c("abbrev") %]'
|
|
|
filename: 'geckoview-[% c("version") %]-[% c("var/osname") %]-[% c("var/build_id") %].tar.gz'
|
|
|
git_hash: 'geckoview-[% c("var/geckoview_version") %]-[% c("var/torbrowser_branch") %]-2-build2'
|
|
|
tag_gpg_id: 1
|
|
|
git_url: https://git.torproject.org/tor-browser.git
|
|
|
git_submodule: 1
|
|
|
gpg_keyring: torbutton.gpg
|
|
|
|
|
|
var:
|
|
|
geckoview_version: 99.0b3
|
|
|
torbrowser_branch: 11.5
|
|
|
```
|
|
|
|
|
|
And near the bottom of that file we have:
|
|
|
|
|
|
```
|
|
|
targets:
|
|
|
nightly:
|
|
|
git_hash: 'geckoview-[% c("var/geckoview_version") %]-[% c("var/torbrowser_branch") %]-2'
|
|
|
tag_gpg_id: 0
|
|
|
```
|
|
|
|
|
|
The branch we want to build is the `git_hash` as defined under `targets.nightly`. This is `geckoview-[% c("var/geckoview_version") %]-[% c("var/torbrowser_branch") %]-2`, now we simply fill in the variables with concrete values:
|
|
|
- `geckoview_version` is `99.0b3`
|
|
|
- `torbrowser_branch` is `11.5`
|
|
|
|
|
|
|
|
|
```
|
|
|
cd tor-browser
|
|
|
git checkout geckoview-99.0b3-11.5-2
|
|
|
git submodule update
|
|
|
```
|
|
|
|
|
|
Next, run `mach bootstrap` and let Mozilla's tooling downloading the required packages.
|
|
|
|
|
|
```
|
|
|
$ ./mach bootstrap
|
|
|
```
|
|
|
|
|
|
At the first menu, you most likely want option `4. GeckoView/Firefox for Android`. Accept the license agreement. You can decline optimizations, if you don't want them.
|
|
|
|
|
|
|
|
|
```
|
|
|
Your system should be ready to build GeckoView/Firefox for Android!
|
|
|
|
|
|
Paste the lines between the chevrons (>>> and <<<) into
|
|
|
/home/user/tor-browser/.mozconfig:
|
|
|
|
|
|
>>>
|
|
|
# Build GeckoView/Firefox for Android:
|
|
|
ac_add_options --enable-application=mobile/android
|
|
|
# Targeting the following architecture.
|
|
|
# For regular phones, no --target is needed.
|
|
|
# For x86 emulators (and x86 devices, which are uncommon):
|
|
|
# ac_add_options --target=i686
|
|
|
# For newer phones or Apple silicon
|
|
|
# ac_add_options --target=aarch64
|
|
|
# For x86_64 emulators (and x86_64 devices, which are even less common):
|
|
|
# ac_add_options --target=x86_64
|
|
|
|
|
|
<<<
|
|
|
```
|
|
|
|
|
|
There is a `.mozconfig-android` in the tree, but it needs some updating. Instead, we'll create a new `mozconfig` for the Android build. We'll assume a `x86_64` target. Put this in a new file named `.mozconfig-android2`:
|
|
|
|
|
|
```
|
|
|
mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/obj-x86_64-linux-android
|
|
|
mk_add_options MOZ_APP_DISPLAYNAME="Tor Browser"
|
|
|
|
|
|
# Build GeckoView/Firefox for Android:
|
|
|
ac_add_options --enable-application=mobile/android
|
|
|
ac_add_options --target=x86_64
|
|
|
|
|
|
ac_add_options --enable-optimize
|
|
|
ac_add_options --enable-rust-simd
|
|
|
ac_add_options --enable-official-branding
|
|
|
|
|
|
# https://bugzilla.mozilla.org/show_bug.cgi?id=1758568
|
|
|
ac_add_options --enable-minify=properties
|
|
|
|
|
|
# We do not use Tor Launcher on Android:
|
|
|
ac_add_options --disable-tor-launcher
|
|
|
|
|
|
ac_add_options --disable-tor-browser-update
|
|
|
ac_add_options --disable-verify-mar
|
|
|
|
|
|
# We only use beta GeckoView for now; use default for local builds
|
|
|
ac_add_options --enable-update-channel=default
|
|
|
|
|
|
ac_add_options --enable-strip
|
|
|
ac_add_options --disable-tests
|
|
|
ac_add_options --disable-debug
|
|
|
ac_add_options --disable-rust-debug
|
|
|
ac_add_options --disable-crashreporter
|
|
|
ac_add_options --disable-webrtc
|
|
|
ac_add_options --disable-parental-controls
|
|
|
|
|
|
ac_add_options --enable-proxy-bypass-protection
|
|
|
|
|
|
# Disable telemetry
|
|
|
ac_add_options MOZ_TELEMETRY_REPORTING=
|
|
|
```
|
|
|
|
|
|
This content is based on the config we use in [Tor Browser Build](https://gitlab.torproject.org/tpo/applications/tor-browser-build/-/blob/master/projects/geckoview/mozconfig-android-x86_64).
|
|
|
|
|
|
Note: `--enable-update-channel=default`. This is necessary.
|
|
|
|
|
|
#### Android-Components
|
|
|
|
|
|
Create a `local.properties` in the root (top level) of the repository. Within it, put:
|
|
|
|
|
|
```
|
|
|
dependencySubstitutions.geckoviewTopsrcdir=/home/user/tor-browser
|
|
|
dependencySubstitutions.geckoviewTopobjdir=/home/user/tor-browser/obj-x86_64-linux-android/
|
|
|
```
|
|
|
|
|
|
And replace `/home/user/` with the correct absolute path for the `tor-browser` repo.
|
|
|
|
|
|
|
|
|
#### Fenix
|
|
|
|
|
|
Fenix has a two-step setup process.
|
|
|
|
|
|
First, like `android-components`, create a `local.properties` in the root (top level) of the repository. Within it, put:
|
|
|
|
|
|
```
|
|
|
dependencySubstitutions.geckoviewTopsrcdir=/home/user/tor-browser
|
|
|
dependencySubstitutions.geckoviewTopobjdir=/home/user/tor-browser/obj-x86_64-linux-android/
|
|
|
autoPublish.android-components.dir=/home/user/android-components
|
|
|
```
|
|
|
|
|
|
And replace `/home/user/` with the correct absolute path for the `tor-browser` and `android-components` repositories.
|
|
|
|
|
|
Second, we must manually provide the `tor-android-service` and `tor-onion-proxy-library` build artifacts. This guide assumes you already built them using `tor-browser-build` (such as via https://gitlab.torproject.org/tpo/applications/tor-browser/-/wikis/Hacking/Hacking#reproducing-an-existing-build).
|
|
|
|
|
|
Three files:
|
|
|
- `service-release.aar`
|
|
|
- `android-release.aar`
|
|
|
- `universal-0.0.3.jar`
|
|
|
|
|
|
Copy `service-release.aar` from the most recent and/or up-to-date build of `tor-android-service` from `tor-browser-build`:
|
|
|
|
|
|
```
|
|
|
$ ls -ltr /home/user/tor-browser-build/out/tor-android-service/ | tail -1
|
|
|
drwxr-xr-x 2 android android 4096 Apr 28 09:12 tor-android-service-0f264c889190-bb3c89
|
|
|
$ cp /home/user/tor-browser-build/out/tor-android-service/tor-android-service-0f264c889190-bb3c89/service-release.aar /home/user/fenix/app/
|
|
|
```
|
|
|
|
|
|
Again, replace `/home/user/` with the appropriate absolute or relative paths.
|
|
|
|
|
|
Similarly, we'll copy the artifacts from `tor-onion-proxy-library`:
|
|
|
|
|
|
```
|
|
|
$ ls -ltr /home/user/tor-browser-build/out/tor-onion-proxy-library/ | tail -1
|
|
|
drwxr-xr-x 2 android android 4096 Apr 28 08:07 tor-onion-proxy-library-aeb63ebd079b-691a19
|
|
|
$ cp /home/user/tor-browser-build/out/tor-onion-proxy-library/tor-onion-proxy-library-aeb63ebd079b-691a19/* /home/user/fenix/app/
|
|
|
```
|
|
|
|
|
|
You can compile these libraries on their own, but this guide does not provide those steps at this time - please add them!
|
|
|
|
|
|
### Compiling Geckoview
|
|
|
|
|
|
First, we configure:
|
|
|
|
|
|
```
|
|
|
$ MOZCONFIG=.mozconfig-android2 ./mach configure --with-tor-browser-version=tbb-nightly --without-wasm-sandboxed-libraries
|
|
|
[...]
|
|
|
0:11.83 Creating config.status
|
|
|
0:12.17 Reticulating splines...
|
|
|
0:12.67 0:00.53 File already read. Skipping: /home/user/tor-browser/intl/components/moz.build
|
|
|
0:12.97 0:00.83 File already read. Skipping: /home/user/tor-browser/gfx/angle/targets/angle_common/moz.build
|
|
|
0:18.14 Finished reading 1086 moz.build files in 1.81s
|
|
|
0:18.14 Read 58 gyp files in parallel contributing 0.00s to total wall time
|
|
|
0:18.14 Processed into 6389 build config descriptors in 1.43s
|
|
|
0:18.14 RecursiveMake backend executed in 2.32s
|
|
|
0:18.14 2197 total backend files; 2197 created; 0 updated; 0 unchanged; 0 deleted; 22 -> 771 Makefile
|
|
|
0:18.14 FasterMake backend executed in 0.22s
|
|
|
0:18.14 9 total backend files; 9 created; 0 updated; 0 unchanged; 0 deleted
|
|
|
0:18.14 Total wall time: 5.99s; CPU time: 5.78s; Efficiency: 96%; Untracked: 0.22s
|
|
|
0:18.14 =============
|
|
|
0:18.14 ADVERTISEMENT
|
|
|
0:18.14
|
|
|
0:18.14 You are building GeckoView. After your build completes, you can open
|
|
|
0:18.14 the top source directory in Android Studio directly and build using Gradle.
|
|
|
0:18.14 See the documentation at
|
|
|
0:18.14
|
|
|
0:18.14 https://firefox-source-docs.mozilla.org/mobile/android/geckoview/contributor/geckoview-quick-start.html#build-using-android-studio
|
|
|
0:18.14 =============
|
|
|
Configure complete!
|
|
|
Be sure to run |mach build| to pick up any changes
|
|
|
```
|
|
|
|
|
|
Second, we build:
|
|
|
```
|
|
|
$ MOZCONFIG=.mozconfig-android2 ./mach build
|
|
|
[...]
|
|
|
51:39.42 /usr/bin/notify-send --app-name=Mozilla Build System Mozilla Build System Build complete
|
|
|
To view resource usage of the build, run |mach resource-usage|.
|
|
|
51:39.59 We know it took a while, but your build finally finished successfully!
|
|
|
51:39.59 If you are building Firefox often, SCCache can save you a lot of time. You can learn more here: https://firefox-source-docs.mozilla.org/setup/configuring_build_options.html#sccache
|
|
|
For more information on what to do now, see https://firefox-source-docs.mozilla.org/setup/contributing_code.html
|
|
|
$ MOZCONFIG=.mozconfig-android2 ./mach build binaries && MOZCONFIG=.mozconfig-android2 ./mach gradle geckoview:publishWithGeckoBinariesDebugPublicationToMavenRepository
|
|
|
0:10.35 Overall system resources - Wall time: 9s; CPU: 28%; Read bytes: 317546496; Write bytes: 7307264; Read time: 2583; Write time: 68
|
|
|
To view resource usage of the build, run |mach resource-usage|.
|
|
|
0:10.36 Your build was successful!
|
|
|
[...]
|
|
|
:machStagePackage> make: Leaving directory '/home/user/tor-browser/obj-x86_64-linux-android/mobile/android/installer'
|
|
|
:machStagePackage> make: Leaving directory '/home/user/tor-browser/obj-x86_64-linux-android/mobile/android/installer'
|
|
|
|
|
|
BUILD SUCCESSFUL in 34s
|
|
|
39 actionable tasks: 5 executed, 34 up-to-date
|
|
|
```
|
|
|
|
|
|
There are three commands involved:
|
|
|
1. `MOZCONFIG=.mozconfig-android2 ./mach build`
|
|
|
1. `MOZCONFIG=.mozconfig-android2 ./mach build binaries`
|
|
|
1. `MOZCONFIG=.mozconfig-android2 ./mach gradle geckoview:publishWithGeckoBinariesDebugPublicationToMavenRepository`
|
|
|
|
|
|
The resulting, aar (Android Archive) is under `obj-x86_64-linux-android/gradle/maven/org/mozilla/geckoview/geckoview-beta-omni/`, such as:
|
|
|
|
|
|
```
|
|
|
$ find obj-x86_64-linux-android/gradle/maven/org/mozilla/geckoview/geckoview-beta-omni/ -name *.aar
|
|
|
obj-x86_64-linux-android/gradle/maven/org/mozilla/geckoview/geckoview-beta-omni/99.0.20220506224557-SNAPSHOT/geckoview-beta-omni-99.0.20220506224557-20220506.233506-1.aar
|
|
|
```
|
|
|
|
|
|
If you are compiling a `release` version (not `beta` or `nightly`), then modify `substitute-local-geckoview.gradle` like the below patch, adding `geckoview-omni` as a valid package name:
|
|
|
|
|
|
```diff
|
|
|
diff --git a/substitute-local-geckoview.gradle b/substitute-local-geckoview.gradle
|
|
|
index a32dc5ae8a05..f740d7c7effd 100644
|
|
|
--- a/substitute-local-geckoview.gradle
|
|
|
+++ b/substitute-local-geckoview.gradle
|
|
|
@@ -138,6 +138,11 @@ configurations.all { config ->
|
|
|
'geckoview-beta-omni-arm64-v8a',
|
|
|
'geckoview-beta-omni-x86',
|
|
|
'geckoview-beta-omni-x86_64',
|
|
|
+ 'geckoview-omni',
|
|
|
+ 'geckoview-omni-armeabi-v7a',
|
|
|
+ 'geckoview-omni-arm64-v8a',
|
|
|
+ 'geckoview-omni-x86',
|
|
|
+ 'geckoview-omni-x86_64',
|
|
|
]
|
|
|
|
|
|
if (config.isCanBeResolved()) {
|
|
|
```
|
|
|
|
|
|
### Compiling Android-Components
|
|
|
|
|
|
```
|
|
|
JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64 ANDROID_SDK_ROOT=~/.mozbuild/android-sdk-linux/ ./gradlew assemble
|
|
|
[substitute-local-geckoview] Will substitute GeckoView (geckoview-{nightly,beta}) with local GeckoView (geckoview-default) from /home/user/tor-browser/obj-x86_64-linux-android//gradle/build/mobile/android/geckoview/maven
|
|
|
[substitute-local-geckoview] To update the local GeckoView, run `./mach build binaries && ./mach gradle geckoview:publishWithGeckoBinariesDebugPublicationToMavenRepository` in /home/user/tor-browser
|
|
|
[...]
|
|
|
[substitute-local-geckoview] Substituting org.mozilla.geckoview:geckoview-omni with local GeckoView org.mozilla.geckoview:geckoview-default-omni in configuration ':browser-engine-gecko:releaseRuntimeClasspath'
|
|
|
[substitute-local-geckoview] Substituting org.mozilla.geckoview:geckoview-omni with local GeckoView org.mozilla.geckoview:geckoview-default-omni in configuration ':browser-engine-gecko:releaseCompileClasspath'
|
|
|
[substitute-local-geckoview] Substituting org.mozilla.geckoview:geckoview-omni with local GeckoView org.mozilla.geckoview:geckoview-default-omni in configuration ':browser-engine-gecko:debugRuntimeClasspath'
|
|
|
[substitute-local-geckoview] Substituting org.mozilla.geckoview:geckoview-omni with local GeckoView org.mozilla.geckoview:geckoview-default-omni in configuration ':browser-engine-gecko:debugCompileClasspath'
|
|
|
[substitute-local-geckoview] Substituting org.mozilla.geckoview:geckoview-omni with local GeckoView org.mozilla.geckoview:geckoview-default-omni in configuration ':samples-browser:geckoDebugRuntimeClasspath'
|
|
|
[substitute-local-geckoview] Substituting org.mozilla.geckoview:geckoview-omni with local GeckoView org.mozilla.geckoview:geckoview-default-omni in configuration ':samples-browser:geckoDebugCompileClasspath'
|
|
|
[substitute-local-geckoview] Substituting org.mozilla.geckoview:geckoview-omni with local GeckoView org.mozilla.geckoview:geckoview-default-omni in configuration ':samples-compose-browser:releaseRuntimeClasspath'
|
|
|
[substitute-local-geckoview] Substituting org.mozilla.geckoview:geckoview-omni with local GeckoView org.mozilla.geckoview:geckoview-default-omni in configuration ':samples-compose-browser:releaseCompileClasspath'
|
|
|
[substitute-local-geckoview] Substituting org.mozilla.geckoview:geckoview-omni with local GeckoView org.mozilla.geckoview:geckoview-default-omni in configuration ':samples-compose-browser:releaseUnitTestRuntimeClasspath'
|
|
|
[substitute-local-geckoview] Substituting org.mozilla.geckoview:geckoview-omni with local GeckoView org.mozilla.geckoview:geckoview-default-omni in configuration ':samples-compose-browser:releaseUnitTestCompileClasspath'
|
|
|
[substitute-local-geckoview] Substituting org.mozilla.geckoview:geckoview-omni with local GeckoView org.mozilla.geckoview:geckoview-default-omni in configuration ':samples-compose-browser:debugRuntimeClasspath'
|
|
|
[substitute-local-geckoview] Substituting org.mozilla.geckoview:geckoview-omni with local GeckoView org.mozilla.geckoview:geckoview-default-omni in configuration ':samples-compose-browser:debugCompileClasspath'
|
|
|
[...]
|
|
|
BUILD SUCCESSFUL in 7m 33s
|
|
|
6168 actionable tasks: 2704 executed, 1525 from cache, 1939 up-to-date
|
|
|
```
|
|
|
|
|
|
You may need to specify `JAVA_HOME` and/or `ANDROID_SDK_ROOT`. `android-components` requires java-11, at the time of writing, and you can manually provide the path to a jdk-11 installation if that isn't the default. `ANDROID_SDK_ROOT` is a path to the required Android SDK (in this case, using the one Mozilla downloaded for geckoview).
|
|
|
|
|
|
### Compiling Fenix
|
|
|
|
|
|
```
|
|
|
$ JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64 ANDROID_SDK_ROOT=~/.mozbuild/android-sdk-linux/ ./gradlew clean app:assembleDebug
|
|
|
[settings] Loaded local.properties
|
|
|
[settings] Disabled auto-publication of application-services. Enable it by settings 'autoPublish.application-services.dir' in local.properties
|
|
|
[settings] Enabling automatic publication of android-components from: /home/user/android-components
|
|
|
Contents have not changed, no need to publish
|
|
|
[settings] Published android-components for local development.
|
|
|
|
|
|
> Configure project :app
|
|
|
[...]
|
|
|
|
|
|
BUILD SUCCESSFUL in 7m 56s
|
|
|
50 actionable tasks: 48 executed, 2 up-to-date
|
|
|
```
|
|
|
|
|
|
Now you should have an apk in `app/build/outputs/apk/debug/` (or `beta`, etc., if built for a different variant).
|
|
|
|
|
|
|
|
|
If you receive an error similar to the below, then please review the above Setup instructions.
|
|
|
|
|
|
```
|
|
|
> Task :app:dataBindingMergeDependencyArtifactsDebug FAILED
|
|
|
|
|
|
FAILURE: Build failed with an exception.
|
|
|
|
|
|
* What went wrong:
|
|
|
Execution failed for task ':app:dataBindingMergeDependencyArtifactsDebug'.
|
|
|
> Could not resolve all files for configuration ':app:debugCompileClasspath'.
|
|
|
> Failed to transform service-release.aar to match attributes {artifactType=android-databinding}.
|
|
|
> Execution failed for IdentityTransform: /home/user/fenix/app/service-release.aar.
|
|
|
> File/directory does not exist: /home/user/fenix/app/service-release.aar
|
|
|
> Failed to transform android-release.aar to match attributes {artifactType=android-databinding}.
|
|
|
> Execution failed for IdentityTransform: /home/user/fenix/app/android-release.aar.
|
|
|
> File/directory does not exist: /home/user/fenix/app/android-release.aar
|
|
|
```
|
|
|
|
|
|
### Final Bundling
|
|
|
|
|
|
Now, we must include three components in the apk we built:
|
|
|
1. Noscript
|
|
|
1. https-everywhere
|
|
|
1. allowed_addons.json
|
|
|
|
|
|
Again, we use the assets from `tor-browser-build`:
|
|
|
|
|
|
```
|
|
|
$ mkdir -p assets/extensions
|
|
|
$ cp /home/user/tor-browser-build/out/tor-browser/noscript_security_suite-11.4.5-an+fx.xpi assets/extensions/'{73a6fe31-595d-460b-a920-fcc0f8843232}.xpi'
|
|
|
$ unzip -d assets/extensions/https-everywhere ../tor-browser-build/out/https-everywhere/https-everywhere-2021.7.13-0fc77a.xpi
|
|
|
Archive: ../tor-browser-build/out/https-everywhere/https-everywhere-2021.7.13-0fc77a.xpi
|
|
|
inflating: assets/extensions/META-INF/cose.manifest
|
|
|
inflating: assets/extensions/META-INF/cose.sig
|
|
|
inflating: assets/extensions/META-INF/manifest.mf
|
|
|
[...]
|
|
|
$ cp ../tor-browser-build/projects/tor-browser/allowed_addons.json assets/
|
|
|
$ zip -r app/build/outputs/apk/debug/app-x86_64-debug.apk assets/
|
|
|
updating: assets/allowed_addons.json (deflated 67%)
|
|
|
updating: assets/ (stored 0%)
|
|
|
adding: assets/extensions/ (stored 0%)
|
|
|
adding: assets/extensions/{73a6fe31-595d-460b-a920-fcc0f8843232}.xpi (deflated 2%)
|
|
|
adding: assets/extensions/https-everywhere/ (stored 0%)
|
|
|
adding: assets/extensions/https-everywhere/wasm/ (stored 0%)
|
|
|
```
|
|
|
|
|
|
Finally, re-align the zip and sign it. Here we use the QA signing key in `tor-browser-build`.
|
|
|
|
|
|
```
|
|
|
$ ~/.mozbuild/android-sdk-linux/build-tools/31.0.0/zipalign -vp 4 app/build/outputs/apk/debug/app-x86_64-debug.apk app-x86_64-debug-unsigned.apk
|
|
|
[...]
|
|
|
Verification succesful
|
|
|
$ ~/.mozbuild/android-sdk-linux/build-tools/31.0.0/apksigner sign --verbose --min-sdk-version 21 --ks /home/user/tor-browser-build/projects/tor-browser/android-qa.keystore --out app-x86_64-debug-qa.apk --in app-x86_64-debug-unsigned.apk --ks-key-alias androidqakey --key-pass pass:android --ks-pass pass:android
|
|
|
Signed
|
|
|
```
|
|
|
|
|
|
# Running Multiple Tor Browsers
|
|
|
|
|
|
Now that you have a developer build (or several builds), you probably want to know how to run more than one of them at once. There are two main ways to do this: reusing an existing Tor process, and launching Tor process on a new pair of SOCKS and Control ports.
|
|
|
|
|
|
## Using an Existing Tor Process
|
|
|
|
|
|
Let's assume that Tor process is listening on port 9150 for SOCKS, and 9151 for the control port.
|
|
|
|
|
|
```
|
|
|
export TOR_SOCKS_PORT=9150
|
|
|
export TOR_CONTROL_PORT=9151
|
|
|
export TOR_CONTROL_COOKIE_AUTH_FILE=~/tbb/tor-browser_en-US/Browser/TorBrowser/Data/Tor/control_auth_cookie
|
|
|
export TOR_SKIP_LAUNCH=1
|
|
|
|
|
|
cd $INSTDIR # from the 'Partial Builds' section above
|
|
|
./start-tor-browser.desktop
|
|
|
```
|
|
|
|
|
|
## Launching Tor with an Alternate SOCKS and Control port
|
|
|
|
|
|
If you need to test Tor Launcher changes, you probably want to launch the Tor process too. Here's a quick hack to put that on a different port pair (9250 and 9251):
|
|
|
|
|
|
```
|
|
|
export TOR_SOCKS_PORT=9250
|
|
|
export TOR_CONTROL_PORT=9251
|
|
|
unset TOR_SKIP_LAUNCH
|
|
|
unset TOR_CONTROL_COOKIE_AUTH_FILE
|
|
|
|
|
|
cd $INSTDIR # From the 'Partial Builds' section above
|
|
|
./start-tor-browser.desktop
|
|
|
```
|
|
|
|
|
|
# Tor Browser Team Communication and Organizational Patterns
|
|
|
|
|
|
The Tor Browser development team is very geographically distributed. We use a few different written forms of communication to discuss development over the Internet: Mailing lists, IRC, and this bug tracker. We also hold weekly IRC meetings.
|
|
|
|
|
|
## Communication Mechanisms and Meetings
|
|
|
|
|
|
The mailinglist for Tor Browser development discussion is [tbb-dev](https://lists.torproject.org/pipermail/tbb-dev/). You can also subscribe to the list of Tor Browser code commits via [tbb-commits](https://lists.torproject.org/pipermail/tbb-commits/). All updates to Tor Browser specific bugs are sent to [tbb-bugs](https://lists.torproject.org/pipermail/tbb-bugs/). Release tags and test builds are posted to [tor-qa](https://lists.torproject.org/pipermail/tor-qa/) for community review and testing.
|
|
|
|
|
|
Our primary mode of day-to-day communication is the #tor-dev IRC channel on irc.oftc.net (port 6697 is ssl). We hold weekly meetings on this IRC channel at 19:00 UTC on Mondays. For details on our meeting format, please see the [original meeting announcement post](https://lists.torproject.org/pipermail/tbb-dev/2014-February/000000.html) (note however that the time has changed since that posting).
|
|
|
|
|
|
## How we use Trac
|
|
|
|
|
|
For historical reasons, Tor Browser tickets are spread across several Trac components: "Tor bundles/installation", "TorBrowserButton", "Firefox Patch Issues", and "Tor Launcher". We are considering consolidating many of these components and switching to keywords instead, but that hasn't happened yet.
|
|
|
|
|
|
### Trac Keywords
|
|
|
|
|
|
What follows is a partial list of trac keywords we use to categorize issues, independent of the component they actually arise in.
|
|
|
|
|
|
[tbb-crash](https://trac.torproject.org/projects/tor/query?status=!closed&keywords=~tbb-crash)::
|
|
|
Tickets that represent reported crash or hang issues
|
|
|
[tbb-usability](https://trac.torproject.org/projects/tor/query?status=!closed&keywords=~tbb-usability)::
|
|
|
Tickets that represent usability issues. Has many subcategories as suffixes of tbb-usability.
|
|
|
[tbb-usability-stoppoint](https://trac.torproject.org/projects/tor/query?status=!closed&keywords=~tbb-usability-stoppoint)::
|
|
|
Tickets that represent usability issues that cause users to be unable to use TBB (this is a subset of the previous query)
|
|
|
[tbb-helpdesk-frequent](https://trac.torproject.org/projects/tor/query?status=!closed&keywords=~tbb-helpdesk-frequent)::
|
|
|
Tickets that represent frequently encountered support issues or blog/twitter commentary
|
|
|
[tbb-linkability](https://trac.torproject.org/projects/tor/query?status=!closed&keywords=~tbb-linkability)::
|
|
|
Tickets that represent a violation of our identifier unlinkability [Privacy Requirement](https://www.torproject.org/projects/torbrowser/design/#privacy).
|
|
|
[tbb-fingerprinting](https://trac.torproject.org/projects/tor/query?status=!closed&keywords=~tbb-fingerprinting)::
|
|
|
Tickets that represent a violation of our fingerprinting unlinkability [Privacy Requirement](https://www.torproject.org/projects/torbrowser/design/#privacy). There are many subcategories of this tag as suffixes.
|
|
|
[tbb-disk-leak](https://trac.torproject.org/projects/tor/query?status=!closed&keywords=~tbb-disk-leak)::
|
|
|
Tickets that represent a violation of our Disk Avoidance [Security Requirement](https://www.torproject.org/projects/torbrowser/design/#security).
|
|
|
[tbb-newnym](https://trac.torproject.org/projects/tor/query?status=!closed&keywords=~tbb-newnym)::
|
|
|
Tickets for problems with "New Identity"
|
|
|
[tbb-testcase](https://trac.torproject.org/projects/tor/query?keywords=~tbb-testcase)::
|
|
|
Tickets for which we would like to have an automated testcase to prevent regressions.
|
|
|
[tbb-security](https://trac.torproject.org/projects/tor/query?status=!closed&keywords=~tbb-security)::
|
|
|
Tickets for hardening TBB against exploitation.
|
|
|
[tbb-needs](https://trac.torproject.org/projects/tor/query?status=!closed&keywords=~tbb-needs)::
|
|
|
Tickets in other Tor components that TBB needs solved.
|
|
|
[tbb-mobile](https://trac.torproject.org/projects/tor/query?status=!closed&keywords=~tbb-mobile)::
|
|
|
Tickets for work on Tor Browser for mobile in particular
|
|
|
[tbb-spec](https://trac.torproject.org/projects/tor/query?status=!closed&keywords=~tbb-spec)::
|
|
|
Tickets for work on Tor Browser's design documentation
|
|
|
[tbb-security-slider](https://trac.torproject.org/projects/tor/query?status=!closed&keywords=~tbb-security-slider)::
|
|
|
Tickets for work on Tor Browser's security slider
|
|
|
[tbb-update](https://trac.torproject.org/projects/tor/query?status=!closed&keywords=~tbb-update)::
|
|
|
Tickets for work on Tor Browser's update related code.
|
|
|
[tbb-parity](https://trac.torproject.org/projects/tor/query?status=!closed&keywords=~tbb-parity)::
|
|
|
Tickets for work on feature parity between Tor Browser on different platforms.
|
|
|
[tbb-backport](https://trac.torproject.org/projects/tor/query?status=accepted&status=assigned&status=closed&status=merge_ready&status=needs_information&status=needs_review&status=needs_revision&status=new&status=reopened&keywords=%24tbb-backport&order=priority)::
|
|
|
Tickets that we could consider for backporting from the current alpha to the current stable series. The keyword gets cleared with every new major stable release and the cycle start from the beginning.
|
|
|
|
|
|
In addition to this list, if you would like someone to review a patch, you should set the state of that ticket to "needs review" and tag it that that person's name, followed by the year, the month, and the letter 'R'. For example: [MikePerry201311R](https://trac.torproject.org/projects/tor/query?keywords=~MikePerry201311R).
|
|
|
|
|
|
# Design and Core Components
|
|
|
|
|
|
Ok, so you've got the lay of the land now, and want to really dive in. Here's how everything is organized.
|
|
|
|
|
|
## Design Document
|
|
|
|
|
|
At a high level, Tor Browser development is driven by the design document: [The Design and Implementation of the Tor Browser](https://www.torproject.org/projects/torbrowser/design/). This document specifies the [Design Requirements and Philosophy](https://www.torproject.org/projects/torbrowser/design/#DesignRequirements) that guides our development decisions and our modifications to Firefox, provides an [adversary model](https://www.torproject.org/projects/torbrowser/design/#adversary), and provides a [high level description](https://www.torproject.org/projects/torbrowser/design/#Implementation) of the actual changes we have made to Firefox.
|
|
|
|
|
|
## Component Source Repositories
|
|
|
|
|
|
The Tor Browser is actually built from several components. Here are the main ones specific to the browser itself.
|
|
|
|
|
|
### Firefox Branch Repo
|
|
|
|
|
|
We maintain a branch of the latest Firefox "[Extended Support Release](https://www.mozilla.org/en-US/firefox/organizations/)" (ESR) series, to which we have applied multiple patches to satisfy our design requirements and build security needs.
|
|
|
|
|
|
These branches live in the [tor-browser git repo](https://gitweb.torproject.org/tor-browser.git). The branches are named for the Firefox version they are based off of, along with an integer signifying a rebase number. To learn which branch a particular build uses, inspect its version file. The version file lists a tag for the specific commit used. This tag is derived from the branch name and an additional specific build number.
|
|
|
|
|
|
### Torbutton
|
|
|
|
|
|
[Torbutton](https://gitweb.torproject.org/torbutton.git/) is an addon with a long and storied history. It originated as ProxyButton (a simple Firefox addon to toggle proxy settings), which was rethemed by Scott Squires and configured specifically for Tor's proxy settings. After that initial work, Mike Perry began development to address the numerous security issues that arose when browser state from non-Tor activity leaked into Tor browsing mode, and vice-versa. This toggle mode was [deprecated in favor of a standalone browser](https://blog.torproject.org/blog/toggle-or-not-toggle-end-torbutton) several years back.
|
|
|
|
|
|
As a result, Torbutton contains a lot of cruft code specific to the toggle behavior that has not yet been removed, but is otherwise inactive. However, it still provides a few privacy features by way of observers and other extension-level changes to Firefox to improve privacy and Tor security.
|
|
|
|
|
|
### Tor Launcher
|
|
|
|
|
|
[Tor Launcher](https://gitweb.torproject.org/tor-launcher.git) is a Firefox addon that acts as a Tor Controller. It handles launching and configuring Tor for use with the browser. It also is compatible with Thunderbird, InstantBird, and XULRunner, and is used by the [Tails project](https://tails.boum.org/) as well.
|
|
|
|
|
|
### HTTPS-Everywhere
|
|
|
|
|
|
[HTTPS-Everywhere](https://gitweb.torproject.org/https-everywhere.git) contains tens of thousands of URL rewrite rules to enforce HTTPS for sites that support both HTTP and HTTPS URL schemes.
|
|
|
|
|
|
### NoScript
|
|
|
|
|
|
We don't modify NoScript directly, however we do have a number of preferences changes to it and other addons in the [tor-browser-bundle preferences file](https://gitweb.torproject.org/builders/tor-browser-bundle.git/tree/Bundle-Data/mac/TorBrowser/Data/Browser/profile.default/preferences/extension-overrides.js) in the bundle layout directories.
|
|
|
|
|
|
If you're interested in bisecting or otherwise tracking down a particular NoScript change, bug, or issue, avian2 maintains a complete [git repository for NoScript](https://github.com/avian2/noscript), with one commit per NoScript release (including alphas, betas, and rc releases).
|
|
|
|
|
|
### Pluggable Transports
|
|
|
|
|
|
Tor Browser includes several [pluggable transports](https://www.torproject.org/docs/pluggable-transports.html.en), which are a network traffic transformation layer to help avoid censorship and filtering mechanisms. If you are interested in getting your own pluggable transport added to the bundle, the FTE transport work is a good example to follow.
|
|
|
|
|
|
The [original ticket for FTE](https://trac.torproject.org/projects/tor/ticket/10362) is a good starting point. It resulted in a [clean branch](https://gitweb.torproject.org/builders/tor-browser-bundle.git/diff?id=8f8a4cd59bfe07e5b8c12e3990627544d9caeab4&id2=a1bab4013e149eb698a2fe6fb456d96bcf4d520e) that merged easily.
|
|
|
|
|
|
Pluggable Transport Bridges are specified in [the bridge_prefs.js](https://gitweb.torproject.org/builders/tor-browser-bundle.git/tree/Bundle-Data/PTConfigs/bridge_prefs.js) configuration file in the Bundle Skeleton directory.
|
|
|
|
|
|
# Debugging the Tor Browser
|
|
|
|
|
|
There are a few different ways to debug the Tor Browser, depending on the component involved. We'll focus on the extensions and the browser itself here.
|
|
|
|
|
|
## Enabling debug logs in extensions
|
|
|
|
|
|
To enable extension debug logging, set these preferences in your `about:config`:
|
|
|
|
|
|
| SETTING NAME | VALUE |
|
|
|
|----------------------------------|-------|
|
|
|
| extensions.torbutton.loglevel | 2 |
|
|
|
| extensions.torbutton.logmethod | 0 |
|
|
|
| extensions.https_everywhere.LogLevel | 2 |
|
|
|
| extensions.https_everywhere.log_to_stdout | true |
|
|
|
| extensions.torlauncher.loglevel | 2 |
|
|
|
| extensions.torlauncher.logmethod | 0 |
|
|
|
|
|
|
Lower levels are more verbose, but if you go much below 2, you will likely be overwhelmed and/or the browser will be extremely slow.
|
|
|
|
|
|
If you want to save your logs to a file, you need to use the --log argument to start-tor-browser.desktop. It takes an optional filename. Without a filename, it writes tor-browser.log in the current directory:
|
|
|
|
|
|
```
|
|
|
$ ./start-tor-browser.desktop --log
|
|
|
$ tail -f tor-browser.log
|
|
|
```
|
|
|
|
|
|
## Offline Logging/Tracing
|
|
|
|
|
|
Sometimes you need to resort to printf style debugging (for instance, on platforms which do not have debug symbols) or you are diagnosing a race condition that's highly sensitive to timing. In such cases, check out [TbbLogger](https://github.com/pospeselr/tbblogger) ( https://github.com/pospeselr/tbblogger ).
|
|
|
|
|
|
Apply the TbbLogger.patch to your firefox sources and you will be able to include the TbbLogger.h header throughout the firefox code base. This header defines two macros for your enjoyment: **TBB_LOG**(format-string, ...) and **TBB_TRACE**().
|
|
|
|
|
|
The **TBB_LOG** macro allow tracing using fmtlib ( http://fmtlib.net/latest/syntax.html ) formatting with some extra debug info: timestamp, parent/child content process, thread id, and log location. The **TBB_TRACE** macro does not include any message. This information, plus your format-string and args, are serialized to disk on a background thread as a binary blob. Logs are converted to plain-text via an offline 'aggregate' tool which will convert the binary blob to formatted messages sorted by timestamp. The timestamps ensure that messages are written in the order they actually happened, even between the parent and child content processes.
|
|
|
|
|
|
### Example Usage
|
|
|
|
|
|
#### Source
|
|
|
|
|
|
```
|
|
|
...
|
|
|
#include "TbbLogger.h"
|
|
|
...
|
|
|
void function_name()
|
|
|
{
|
|
|
...
|
|
|
TBB_TRACE();
|
|
|
int some_int = 100;
|
|
|
double some_double = 34.0;
|
|
|
TBB_LOG("This is some logging %i %f", some_int, some_double);
|
|
|
...
|
|
|
}
|
|
|
```
|
|
|
|
|
|
#### Aggregate
|
|
|
|
|
|
```
|
|
|
$ ./aggregate /tmp/firefox/*.bin
|
|
|
[0.000323][Parent][29958] function_name in Test.cpp:18
|
|
|
[0.000324][Parent][29958] function_name in Test.cpp:22 This is some logging 100 34.000000
|
|
|
```
|
|
|
|
|
|
## Using the Javascript Debugger
|
|
|
|
|
|
XXX: Write or link to some documentation on using Venkman/JSD for extension debugging. There are two options for this: Venkman and the in-browser debugger. For TBB pre-5.0, Venkman was the way (https://addons.mozilla.org/en-us/firefox/addon/javascript-debugger/). However, it is no longer supported. Instead, the built-in debugger must be used:
|
|
|
https://developer.mozilla.org/en-US/docs/Debugging_JavaScript#JavaScript_Debugger
|
|
|
|
|
|
## Debugging on Windows
|
|
|
|
|
|
Firstly, ignore the 'Using gdb' section immediately after this one, that's only for Linux. Then go to [DebuggingOnWindows](https://trac.torproject.org/projects/tor/wiki/doc/TorBrowser/Hacking/DebuggingOnWindows)
|
|
|
|
|
|
## Using gdb
|
|
|
|
|
|
### Using Debug Symbols
|
|
|
|
|
|
If you're going to use GDB to debug an issue, the first thing you want is debug symbols. Tor Browser builds detached debug symbols for tor and firefox.
|
|
|
|
|
|
In the bundle release download directory there should be a `tor-browser-linux64-debug.zip` file. Unfortunately, the directory structure of the debug zip doesn't exactly match what you need in order for gdb to find the symbols automatically. For the tor-browser-linux symbols, unzip the file in the bundle root directory, and then relocate it to the .debug subdirectory of Browser, like so:
|
|
|
|
|
|
```
|
|
|
$ cd tor-browser_en-US
|
|
|
$ wget https://dist.torproject.org/torbrowser/8.5a11/tor-browser-linux64-debug.tar.xz
|
|
|
$ tar xavf tor-browser-linux64-debug.tar.xz
|
|
|
$ mv Debug/Browser Browser/.debug
|
|
|
$ gdb ./Browser/firefox.real
|
|
|
```
|
|
|
|
|
|
At this point, gdb should find all of the Firefox symbols automatically upon every invocation, and you can either attach to an existing process ID or launch firefox directly, as described in the following sections below.
|
|
|
|
|
|
### Attaching an already running TBB
|
|
|
|
|
|
You can attach a gdb instance to an already running TBB firefox process. To do this, find the pid of your running TBB firefox.real, then tell gdb to attach the running process (note that on some systems you may need to run gdb as root for this to work):
|
|
|
|
|
|
```
|
|
|
$ for p in `pgrep firefox.real` ; do ps -v $p ; done
|
|
|
[...find the pid for your TBB firefox...]
|
|
|
$ gdb ./Browser/firefox.real
|
|
|
(gdb) attach <pid>
|
|
|
```
|
|
|
|
|
|
### Starting firefox from inside gdb
|
|
|
|
|
|
Assuming you run an alpha build, starting firefox inside gdb:
|
|
|
|
|
|
```
|
|
|
$ gdb ./Browser/firefox.real
|
|
|
(gdb) set env LD_LIBRARY_PATH=Browser/TorBrowser/Tor
|
|
|
(gdb) set env SELFRANDO_skip_shuffle=
|
|
|
(gdb) run -profile Browser/TorBrowser/Data/Browser/profile.default
|
|
|
```
|
|
|
|
|
|
### Generating and debugging core files
|
|
|
|
|
|
If you have a condition that crashes Tor Browser in an unreliable way, one helpful step is to generate a core file for crashes that do happen. To do this, before launching Tor Browser, run:
|
|
|
```
|
|
|
$ ulimit -c unlimited
|
|
|
```
|
|
|
|
|
|
Then, when Tor Browser crashes, a core file should show up in Browser/core. To debug this core, run:
|
|
|
|
|
|
```
|
|
|
$ gdb ./Browser/firefox ./Browser/core
|
|
|
```
|
|
|
|
|
|
You can then use the usual gdb commands (backtrace, print, up, down, etc) to inspect the stack, variables, and program state at the time of the crash.
|
|
|
|
|
|
### Debugging ASan/selfrando builds
|
|
|
|
|
|
If you need to debug a hardened build that includes [ASan](https://github.com/google/sanitizers/wiki/AddressSanitizer) and [selfrando](https://github.com/immunant/selfrando) you have two options.
|
|
|
|
|
|
#### Temporarily disable selfrando
|
|
|
|
|
|
If you set the environmental variable `SELFRANDO_skip_shuffle`, selfrando will be disabled and gdb will work as usual. E.g.:
|
|
|
|
|
|
```
|
|
|
$ gdb -ex "set env LD_LIBRARY_PATH=$PWD/Browser/TorBrowser/Tor" -ex "set env SELFRANDO_skip_shuffle=" \
|
|
|
-ex 'set env ASAN_OPTIONS="detect_leaks=0,abort_on_error=1"' -ex "set env NSS_DISABLE_HW_AES=1" \
|
|
|
--args Browser/firefox -profile Browser/TorBrowser/Data/Browser/profile.default/
|
|
|
```
|
|
|
|
|
|
#### Convert ASan's stack trace message
|
|
|
|
|
|
This method can be used only to debug a crash. Start Tor Browser with `Browser/start-tor-browser -v`. After the browser crashes, you will see one or more stack traces that look like this:
|
|
|
```
|
|
|
==3896==ERROR: AddressSanitizer: heap-use-after-free on address 0x6040003b85e0 at pc 0x7f5dff50f35d bp 0x7ffe516e3a90 sp 0x7ffe516e3a88
|
|
|
READ of size 4 at 0x6040003b85e0 thread T0
|
|
|
SRAT init
|
|
|
#0 0x7f5dff50f35c (/path/to/directory/tor-browser/Browser/libxul.so+0x4af0a9a)
|
|
|
#1 0x7f5dfe153916 (/path/to/directory/tor-browser/Browser/libxul.so+0x4af0d32)
|
|
|
#2 0x7f5e001ae7f6 (/path/to/directory/tor-browser/Browser/libxul.so+0x392d7e8)
|
|
|
[...]
|
|
|
#43 0x418d98 (/path/to/directory/tor-browser/Browser/firefox+0x4089dc)
|
|
|
#44 0x7f5e0b0d8f44 in __libc_start_main (/lib/x86_64-linux-gnu/libc.so.6+0x21f44)
|
|
|
#45 0x41e9dc (/path/to/directory/tor-browser/Browser/firefox+0x408e34)
|
|
|
```
|
|
|
|
|
|
To get a meaningful stack trace you need to install a symbolizer (you can install `clang` and use `llvm-symbolizer`). Then, copy the relevant text from ASan's output, pipe it trough [[convert-asan-to-symbolizer.py](None/convert-asan-to-symbolizer.py) convert-asan-to-symbolizer.py] and then into the symbolizer. E.g.:
|
|
|
|
|
|
```
|
|
|
$ xsel -b | ./convert-asan-to-symbolizer.py | llvm-symbolizer-3.4
|
|
|
```
|
|
|
|
|
|
The script assumes that debug information is available in `Browser/.debug` (see [#UsingDebugSymbols Using Debug Symbols]).
|
|
|
|
|
|
|
|
|
## Using dtrace
|
|
|
|
|
|
Dtrace is a very powerful tracing and debugging system that requires kernel support, however all the **grown-up** Operating Systems support it (not supported by Linux).
|
|
|
Like many of the powerful creations of Unix, dtrace immediately gave rise to an orgy of one-liners. That is, one-line dtrace programs that perform a useful task! Like **awk**, there are many such dtrace one-liners that people have documented and are still useful today, often with little or no modification. In fact, you can utilize both **dtrace** and **awk** in the same command pipeline to create something even more expressive!
|
|
|
|
|
|
The IllumOS (the new OpenSolaris) kernel has support for **Linux zones** which can run native x86 32bit and 64bit binaries in an isolated environment. They have done such
|
|
|
a good job at this Linux binary system call emulation that it can run all the normal stuff including systemd and other monstrosities such as htop. ;-p
|
|
|
My Debian 8 image indeed acts like a normal Debian 8 system... although it is definitely not running the Linux kernel.
|
|
|
|
|
|
The host's global zone can be used to dtrace native Linux and Solaris zones. Tor Browser Bundle runs fine using the Linux zones.
|
|
|
|
|
|
[Isolating tor applications with SmartOS](https://trac.torproject.org/projects/tor/wiki/doc/TorBrowser/SmartOS_Sandboxing)
|
|
|
|
|
|
onion -> noVNC http -> vnc4server -> tbb
|
|
|
|
|
|
**more dtrace examples**
|
|
|
[https://wiki.smartos.org/display/DOC/DTrace]
|
|
|
|
|
|
|
|
|
### dtrace examples for Tor Browser Bundle
|
|
|
|
|
|
Many of these examples collect dtrace probe information until the operator hits control-c.
|
|
|
I found many dtrace exmamples. Here's some that might be useful:
|
|
|
|
|
|
Which files does firefox open?
|
|
|
```
|
|
|
dtrace -n 'lx-syscall::open*:entry /execname == "firefox"/ { printf("%s %s", execname, copyinstr(arg0)); }
|
|
|
'
|
|
|
dtrace: description 'lx-syscall::open*:entry ' matched 6 probes
|
|
|
CPU ID FUNCTION:NAME
|
|
|
0 3874 open:entry firefox /dev/urandom
|
|
|
0 3874 open:entry firefox /home/human/tor-browser_en-US/Browser/TorBrowser/Tor/libcanberra.so.0
|
|
|
0 3874 open:entry firefox /etc/ld.so.cache
|
|
|
0 3874 open:entry firefox /lib/x86_64-linux-gnu/libcanberra.so.0
|
|
|
0 3874 open:entry firefox /usr/lib/x86_64-linux-gnu/libcanberra.so.0
|
|
|
0 3874 open:entry firefox /lib/libcanberra.so.0
|
|
|
0 3874 open:entry firefox /usr/lib/libcanberra.so.0
|
|
|
0 3874 open:entry firefox /home/human/tor-browser_en-US/Browser/TorBrowser/Tor/libcanberra.so.0
|
|
|
0 3874 open:entry firefox /etc/ld.so.cache
|
|
|
0 3874 open:entry firefox /lib/x86_64-linux-gnu/libcanberra.so.0
|
|
|
0 3874 open:entry firefox /usr/lib/x86_64-linux-gnu/libcanberra.so.0
|
|
|
0 3874 open:entry firefox /lib/libcanberra.so.0
|
|
|
0 3874 open:entry firefox /usr/lib/libcanberra.so.0
|
|
|
0 3874 open:entry firefox /dev/urandom
|
|
|
0 3874 open:entry firefox /dev/urandom
|
|
|
^C
|
|
|
```
|
|
|
|
|
|
syscall frequency count
|
|
|
```
|
|
|
dtrace -n 'lx-syscall:::entry /pid == 44622/ { @num[probefunc] = count(); }'
|
|
|
dtrace: description 'lx-syscall:::entry ' matched 676 probes
|
|
|
^C
|
|
|
|
|
|
read 725
|
|
|
write 725
|
|
|
writev 1400
|
|
|
futex 3548
|
|
|
poll 5686
|
|
|
recvmsg 6911
|
|
|
clock_gettime 17440
|
|
|
```
|
|
|
|
|
|
function and module top 10 frequency count
|
|
|
lx_proc_func_count.d
|
|
|
```
|
|
|
pid$target:::entry {
|
|
|
@a[probemod,probefunc] = count();
|
|
|
}
|
|
|
END { trunc(@a,10); }
|
|
|
```
|
|
|
|
|
|
```
|
|
|
./lx_proc_func_count.d -p 44622
|
|
|
dtrace: script './lx_proc_func_count.d' matched 30865 probes
|
|
|
^C
|
|
|
CPU ID FUNCTION:NAME
|
|
|
0 2 :END
|
|
|
|
|
|
firefox realloc 31609
|
|
|
libmozalloc.so moz_xmalloc 33383
|
|
|
libmozalloc.so moz_free 36504
|
|
|
firefox malloc 50687
|
|
|
firefox free 54604
|
|
|
libpthread.so.0 pthread_self 58444
|
|
|
libpthread.so.0 pthread_getspecific 69741
|
|
|
libpthread.so.0 pthread_mutex_unlock 204393
|
|
|
libpthread.so.0 pthread_mutex_lock 204394
|
|
|
libpthread.so.0 __pthread_mutex_unlock_usercnt
|
|
|
```
|
|
|
|
|
|
**lxsockopt.d**
|
|
|
```
|
|
|
|
|
|
#pragma D option quiet
|
|
|
|
|
|
/**
|
|
|
PROTO values can be found here:
|
|
|
https://en.wikipedia.org/wiki/List_of_IP_protocol_numbers
|
|
|
SOCKOPT values can be found here:
|
|
|
https://github.com/joyent/illumos-joyent/blob/master/usr/src/lib/brand/lx/lx_brand/common/socket.c
|
|
|
*/
|
|
|
BEGIN
|
|
|
{
|
|
|
printf("%6s %20s %5s %s\n", "PID", "NAME", "PROTO", "SOCKOPT");
|
|
|
}
|
|
|
|
|
|
lx-syscall::setsockopt:entry
|
|
|
{
|
|
|
printf("%6d %20s %5d %d\n", pid, execname, arg1, arg2);
|
|
|
}
|
|
|
```
|
|
|
```
|
|
|
./lxsockopt.d
|
|
|
PID NAME PROTO SOCKOPT
|
|
|
44622 firefox 6 1
|
|
|
15388 tor 1 2
|
|
|
44622 firefox 6 4
|
|
|
44622 firefox 6 5
|
|
|
44622 firefox 6 6
|
|
|
44622 firefox 6 4
|
|
|
44622 firefox 6 5
|
|
|
44622 firefox 6 6
|
|
|
44622 firefox 1 9
|
|
|
44622 firefox 6 4
|
|
|
44622 firefox 6 5
|
|
|
44622 firefox 6 6
|
|
|
44622 firefox 1 9
|
|
|
```
|
|
|
|
|
|
track malloc allocations
|
|
|
```
|
|
|
dtrace -n 'pid8880::malloc:entry { printf ("Firefox is asking for %d bytes", arg0); }'
|
|
|
|
|
|
0 74421 malloc:entry Firefox is asking for 24 bytes
|
|
|
0 74421 malloc:entry Firefox is asking for 48 bytes
|
|
|
0 74421 malloc:entry Firefox is asking for 16 bytes
|
|
|
0 74421 malloc:entry Firefox is asking for 32 bytes
|
|
|
0 74421 malloc:entry Firefox is asking for 16 bytes
|
|
|
0 74421 malloc:entry Firefox is asking for 8176 bytes
|
|
|
```
|
|
|
|
|
|
in real-time, find all the code modules which utilize **malloc**:
|
|
|
```
|
|
|
dtrace -l -n 'pid$1::malloc:entry' 1774
|
|
|
|
|
|
ID PROVIDER MODULE FUNCTION NAME
|
|
|
74421 pid1774 firefox malloc entry
|
|
|
74578 pid1774 LMfd`ld.so.1 malloc entry
|
|
|
75306 pid1774 LMfd`libmapmalloc.so.1 malloc entry
|
|
|
76053 pid1774 LMfd`libc.so.1 malloc entry
|
|
|
84541 pid1774 libc.so.6 malloc entry
|
|
|
85794 pid1774 ld-linux-x86-64.so.2 malloc entry
|
|
|
```
|
|
|
|
|
|
|
|
|
## Bisecting
|
|
|
|
|
|
If you found a bug and want to start bisecting to find the exact commit which introduced the problem you have three major cases to consider.
|
|
|
|
|
|
### The easy case
|
|
|
|
|
|
You found your bug is part of either Torbutton, Tor Launcher or HTTPS-Everywhere. In this case you check out the respective repository and do the usual bisecting there. To test the various revisions you can take a clean Tor Browser and load the .xpi's into it. Theoretically, this would work in the NoScript case as well but unfortunately there is no public version control system available and thus if you found a bug in NoScript you need to identify the version it showed first up manually and file a ticket.
|
|
|
|
|
|
### The medium difficult case
|
|
|
|
|
|
Okay, you ruled out a bug in one of the extensions we ship and determined it got introduced by one of our Tor Browser patches or changes to the bundling/build process (testing whether the bug occurs in a corresponding vanilla Firefox is helpful here). The first thing you are doing now is finding out which Tor Browser version is the one that introduced the bug. Using the [Tor Browser archive](https://archive.torproject.org/tor-package-archive/torbrowser/) is a good starting point. If you found the culprit and the bug did not get introduced while switching to a new Firefox ESR (the next section deals with the switching case) chances are high that you don't need to bisect at all. Comparing the changelogs between the last version without the bug and the first version with the bug should be enough in this case. But if the changelogs don't ring a bell and you suspect this is a bug introduced by the build process/bundling looking at the changes introduced in the tor-browser-bundle repository between the two Tor Browser releases should reveal the bad commit. If the changelogs don't help and you suspect an issue with one or more of our Tor Browser patches you need to clone the tor-browser repository and do a normal bisect following the Partial Builds strategy outlined above between the last tor-browser patch of the good Tor Browser and the last tor-browser patch that got into the bad Tor Browser.
|
|
|
|
|
|
### The tricky case
|
|
|
|
|
|
The patchset effectively did not change and you are only switching to a new ESR. There could be three reasons for the bad Tor Browser then. The first one: rebasing one or more patches went wrong. The second one: some change in the new ESR is causing the trouble. The third one: a combination of the first two. The strategy to deal with this group of cases is to rule out the first one (and thus the third one as well) and then narrow down the possible patches that could be affected by changes in the new ESR. These patches in turn are applied during bisecting the commits in the mozilla-central repository that made it into the bad Tor Browser.
|
|
|
|
|
|
### Testing in TaskCluster
|
|
|
|
|
|
If you suspect there is an issue with Tor's toolchain, you can use Tor's toolchain in taskcluster relatively easily, like so: https://hg.mozilla.org/try/rev/bbee5fef95a86824e37a01162cc3ee0a56b1ed3a
|
|
|
|
|
|
## QA and Testing
|
|
|
|
|
|
Some automated tests are run on nightly builds, and new releases. The main page for the results is http://test-reports.tbb.torproject.org/reports/.
|
|
|
|
|
|
If you want to run the test suite yourself, read the [installation instructions](https://people.torproject.org/~boklm/tbbtests-doc/install.html), and the [usage instructions](https://people.torproject.org/~boklm/tbbtests-doc/usage.html). You can also learn [how to add a new test](https://people.torproject.org/~boklm/tbbtests-doc/new-test.html).
|
|
|
|
|
|
The different categories of tests we are running are described below.
|
|
|
|
|
|
### Tor Browser Test Suite
|
|
|
|
|
|
This test suite contains a series of tests to check a Tor Browser Bundle. It is used to check different things:
|
|
|
|
|
|
- the binaries included in the bundle are correctly linked and compiled
|
|
|
- the tor daemon is working, with bridges, some pluggable transports and with an http proxy
|
|
|
- some mozill and selenium tests
|
|
|
|
|
|
The list of tests is defined in [TBBTestSuite/TestSuite/BrowserBundleTests.pm](https://gitweb.torproject.org/user/boklm/tor-browser-bundle-testsuite.git/tree/TBBTestSuite/TestSuite/BrowserBundleTests.pm). [Documentation for adding new tests is available](https://people.torproject.org/~boklm/tbbtests-doc/new-test.html).
|
|
|
|
|
|
This test suite is automatically run in the following cases:
|
|
|
|
|
|
- when a new nightly build is available on https://people.torproject.org/~linus/builds/. An email of the results is sent to a list of people defined in config/linus-nightly. You can ask me if you want to be added to this list.
|
|
|
|
|
|
- when a new release is tagged on git and available on https://people.torproject.org/~user/builds/$version/. The result of the tests is emailed to tor-qa@lists.torproject.org.
|
|
|
|
|
|
- when a Tor Browser developer created a tbb-qa.yml file to request a build to be test. The result of the tests is emailed to the developer requesting the tests. See the section below for details about requesting tests on custum builds.
|
|
|
|
|
|
### VirusTotal uploads
|
|
|
|
|
|
The Windows version of the Tor Browser .exe file is uploaded to virustotal.com to check it with different antivirus. All executable files included in the archive are also uploaded.
|
|
|
|
|
|
The uploads are automatically done in the following cases:
|
|
|
|
|
|
- when a new nightly build is available on https://people.torproject.org/~linus/builds/. The results are available on http://test-reports.tbb.torproject.org/reports/index-browserbundle_virustotal.html. No emails are sent at the moment (you can ask me if you are interested to receive them).
|
|
|
|
|
|
- when a new release is tagged on git and available on https://people.torproject.org/~user/builds/$version/. The results are sent to tor-qa@lists.torproject.org.
|
|
|
|
|
|
|
|
|
### Browser Unit Tests
|
|
|
|
|
|
The Browser Unit Tests are the tests which are included in the Mozilla sources tree (xpcshell and mochitests). The Tor Browser patches can add new tests to be run. Before running those tests, we need to build the sources tree.
|
|
|
|
|
|
We are able to run those tests on a series of commits, and display the differences in the results between each commits and its ancestor.
|
|
|
|
|
|
It is not currently run automatically. In the future, it should be possible to specify a commit or branch to be tested, by editing the tbb-qa.yml file. Until then, you can ask me to edit the config file to test a specific branch or commit.
|
|
|
|
|
|
### Rebasing Tests
|
|
|
|
|
|
A prototype for a rebasing tests has been made. The goal is to try to automatically rebase all Tor Browser patches on the master branch of gecko-dev.
|
|
|
|
|
|
It is not yet run automatically.
|
|
|
|
|
|
## Requesting testing of a custom build using the tbb-qa.yml file
|
|
|
|
|
|
To request a custom build to be tested, you need an account on people.torproject.org and be listed in the [config/testrequests](https://gitweb.torproject.org/user/boklm/tor-browser-bundle-testsuite.git/tree/config/testrequests) file (ask me if you want to be added).
|
|
|
|
|
|
Upload your build to perdulce in directory ~public_html/builds/x.y.z-featureA
|
|
|
|
|
|
Create a file public_html/builds/tbb-qa.yml with permission 744 and a list of build directory names using the YAML syntax:
|
|
|
```
|
|
|
---
|
|
|
- x.y.z-featureA
|
|
|
```
|
|
|
|
|
|
You should receive an email on your @torproject.org email address when the tests finished running. Make sure to include a proper sha256sums.txt file and its signature in the respective build directory.
|
|
|
|
|
|
The tbb-qa.yml file can also be used to request other types of tests. Instead of adding a string which is a directory name in your builds directory, you can add a hash table containing the options for your test requests and a 'type' key containing the type of tests you want to run.
|
|
|
|
|
|
For instance the following tbb-qa.yml file can be used to request a test of type 'browserunit' (Tor Browser unit tests) on a specific commit:
|
|
|
```
|
|
|
---
|
|
|
- type: browserunit
|
|
|
commit: e1a8bafb44367592b
|
|
|
```
|
|
|
|
|
|
The following types of tests are available:
|
|
|
|
|
|
### Tor Browser Unit Tests (xpcshell and mochitest)
|
|
|
|
|
|
type name: browserunit
|
|
|
|
|
|
Options:
|
|
|
|
|
|
- commit: the commit that you want to build and run tests on. This can be a commit hash, tag or branch.
|
|
|
- esr_branch: using this option means that you want all commits from the Mozilla ESR branch to the selected commit to be tested. Example: esr31.
|
|
|
- git_url: the URL of the git repository containing the selected commit. If unspecified, https://git.torproject.org/tor-browser.git is used by default.
|
|
|
|
|
|
### Android
|
|
|
|
|
|
There are two supported way for testing (and developing) Tor Browser on Android.
|
|
|
- Command line
|
|
|
Mozilla provide support for building and running the test suits on an emulator or a device via `mach`. This is the easiest and most straight forward method right now.
|
|
|
|
|
|
- Android Studio
|
|
|
Android Studio provides a nice IDE for developing Android Apps. You can follow the initial build instructions for Android on this page, and then go to Mozilla's [[Studio instructions](https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Build_Instructions/Simple_Firefox_for_Android_build#Developing_Firefox_for_Android_in_Android_Studio|Android)] section: `Developing Firefox for Android in Android Studio`. Following those instructions should get you up and running.
|
|
|
|
|
|
A note on Android emulators. Mozilla Fennec required the ARM processor support [[https://developer.android.com/ndk/guides/cpu-arm-neon|NEON]]. Unfortunately, it seems like Android kernels compiled for older APIs don't support this (?). It's annoying. As an example, compare the CPU Features:
|
|
|
|
|
|
a stock `armeabi-v7a` API 18 emulator does not support that extension:
|
|
|
```
|
|
|
root@generic:/ # uname -a
|
|
|
/system/bin/sh: uname: not found
|
|
|
126|root@generic:/ # cat /proc/sys/kernel/osrelease
|
|
|
3.10.0+
|
|
|
root@generic:/ # cat /proc/sys/kernel/ostype
|
|
|
Linux
|
|
|
root@generic:/ # cat /proc/sys/kernel/version
|
|
|
#8 SMP PREEMPT Mon May 23 14:53:39 PDT 2016
|
|
|
root@generic:/ # cat /proc/sys/kernel/hostname
|
|
|
localhost
|
|
|
root@generic:/ # cat /proc/cpuinfo
|
|
|
processor : 0
|
|
|
model name : ARMv7 Processor rev 1 (v7l)
|
|
|
BogoMIPS : 125.00
|
|
|
Features : swp half thumb fastmult vfp edsp vfpv3 tls vfpv4 idiva idivt vfpd32 evtstrm
|
|
|
CPU implementer : 0x41
|
|
|
CPU architecture: 7
|
|
|
CPU variant : 0x2
|
|
|
CPU part : 0xc0f
|
|
|
CPU revision : 1
|
|
|
|
|
|
Hardware : Dummy Virtual Machine
|
|
|
Revision : 0000
|
|
|
Serial : 0000000000000000
|
|
|
```
|
|
|
|
|
|
a stock `armeabi-v7a` API 24 emulator does support that extension:
|
|
|
|
|
|
```
|
|
|
generic:/ $ uname -a
|
|
|
Linux localhost 3.10.0+ #1 SMP PREEMPT Wed May 18 00:25:13 UTC 2016 armv7l
|
|
|
generic:/ $ cat /proc/cpuinfo
|
|
|
processor : 0
|
|
|
model name : ARMv7 Processor rev 1 (v7l)
|
|
|
BogoMIPS : 125.00
|
|
|
Features : swp half thumb fastmult vfp edsp neon vfpv3 tls vfpv4 idiva idivt vfpd32 evtstrm
|
|
|
CPU implementer : 0x41
|
|
|
CPU architecture: 7
|
|
|
CPU variant : 0x2
|
|
|
CPU part : 0xc0f
|
|
|
CPU revision : 1
|
|
|
|
|
|
Hardware : Dummy Virtual Machine
|
|
|
Revision : 0000
|
|
|
Serial : 0000000000000000
|
|
|
```
|
|
|
|
|
|
# FPCentral
|
|
|
|
|
|
FPCentral is a tool which was created by [Pierre Laperdrix](https://plaperdr.github.io/) as a Google Summer of Code project. We use this tool to detect changes in the fingerprint of new Tor Browser releases.
|
|
|
|
|
|
An instance of FPCentral is available at the following URL: https://fpcentral.tbb.torproject.org/
|
|
|
|
|
|
The git repository containing the sources is at: https://gitweb.torproject.org/fpcentral.git/
|
|
|
|
|
|
The tests for the different fingerprint attributes are defined in the [fingerprint/attributes directory](https://gitweb.torproject.org/fpcentral.git/tree/fingerprint/attributes). If you want to add a new test, you will need to create a javascript file containing a function returning an attribute value, and a json file describing this attribute. See the [README.md file](https://gitweb.torproject.org/fpcentral.git/tree/fingerprint/attributes/README.md) for more details.
|
|
|
|
|
|
When you run the [fingerprint tests](https://fpcentral.tbb.torproject.org/fp) using Tor Browser, it should tell you if all attributes have an acceptable value. The list of acceptable values for each attribute is defined in [the fingerprint/acceptable/torbrowser70.json file](https://gitweb.torproject.org/fpcentral.git/tree/fingerprint/acceptable/torbrowser70.json). When adding a new attribute definition, you should also define an acceptable value in this file.
|
|
|
|
|
|
# Adding New Default Bridges
|
|
|
|
|
|
The [anti-censorship team](https://trac.torproject.org/projects/tor/wiki/org/teams/AntiCensorshipTeam) takes care of adding, maintaining, and monitoring default bridges. There's a [wiki page](https://trac.torproject.org/projects/tor/wiki/doc/TorBrowser/DefaultBridges) that details the process of adding default bridges to Tor Browser.
|
|
|
|
|
|
# Other Resources |