TorBrowserHackingTheNextGeneration

Here are my notes on building Tor Browser yourself.

 _____ ____  _____ _____   _____ _   _ _____ 
|  ___|  _ \| ____| ____| |_   _| | | | ____|
| |_  | |_) |  _| |  _|     | | | |_| |  _|  
|  _| |  _ <| |___| |___    | | |  _  | |___ 
|_|   |_| \_\_____|_____|   |_| |_| |_|_____|
                                             
 _     ___ _____   _    ____  ____  
| |   |_ _|__  /  / \  |  _ \|  _ \ 
| |    | |  / /  / _ \ | |_) | | | |
| |___ | | / /_ / ___ \|  _ <| |_| |
|_____|___/____/_/   \_\_| \_\____/ 
                                    

(The joke is from early Netscape days: https://en.wikipedia.org/wiki/Netscape). The previous instructions, which were a useful foundation for the ones given here, are here.

Background

Running Debian 10 (buster) on a VPS (I used DigitalOcean for this one). The available memory is important: 16 GB is necessary to build. The Mozilla instructions for Firefox claim 8GB, but this will result in an out of memory error from llvm.

Below I sometimes do things "in a hurry" by piping curl into a shell, which is Not Good Practice. You should download those scripts, look at them (or ask someone else to look at them, or both), and when satisfied, run them. Note that it is sometimes possible to detect, from the server side, when someone is piping to the shell, which makes it even more dangerous. At least just download the scripts before running them, even if you don't review them.

Getting the code

• [~10 min] Get the Tor Browser code

  git clone https://git.torproject.org/tor-browser.git
  cd tor-browser

• Checkout a branch. Do

  git branch -a

  to see the branches. For example, in May 2021, you could checkout the branch associated with the most recent release with

  git checkout remotes/origin/tor-browser-78.10.0esr-10.0-1

Satisfying dependencies prior to build

• [~15 min] Install stuff we'll need in one fell swoop:

  sudo apt install --no-install-suggests  --no-install-recommends \
      unzip \
      libglib2.0-dev \
      libgconf2-dev \
      libgtk2.0-dev \
      libgtk-3-dev \
      libdbus-1-dev \
      libdbus-glib-1-dev \
      libpulse-dev \
      yasm \
      libasound2-dev \
      libcurl4-openssl-dev \
      libxt-dev \
      mesa-common-dev \
      autoconf \
      autoconf2.13 \
      libtool \
      libgstreamer-plugins-base1.0-dev \ 
      lsb-release \
      pkg-config \
      g++ \
      libpulse-dev \
      gnupg \
      curl \
      make \
      software-properties-common \
      zip \
      apt-transport-https \
      wget \
      software-properties-common \
      zip

Clone tor-launcher and copy it into place

  cd ..  # get to the parent of the tor-browser directory
  
  git clone https://git.torproject.org/tor-launcher

  cp -r tor-launcher tor-browser/browser/extensions/

If you want to hack on tor-launcher, you should do that separately in the cloned tor-launcher project (not in the copy in browser/extensions). Just be sure to copy over the right version each time you build.

Clone torbutton, and move it into place

  # again return to the parent of the tor-browser and tor-launcher directories. cd as needed.

  git clone https://git.torproject.org/torbutton
  cp -r torbutton tor-browser/toolkit/torproject/

Satisfying Mach

• set up virtualenv

  cd tor-browser  # adjust as needed to enter the project you cloned above.  
  ./mach create-mach-environment

• install cbindgen. First install rustup via the following (note: apt installing rustc and cargo fails!)

      curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

then do

      cargo install cbindgen

• install clang toolchain (oi)

    bash -c "$(wget -O - https://apt.llvm.org/llvm.sh)"

• symlink clang:

     # this starts a new login shell, which will 
     #  load the new PATH variable with clang in it
     sudo -u ${YOURUSERNAME} -i  

     # in the command below, replace "12" with the clang version 
     # that you have (type clang then <TAB> to see)
     ln -s $(which clang-12) /usr/bin/clang

• symlink clang++:

     # replace 12 as needed
     ln -s $(which clang++-12) /usr/bin/clang++

• symlink llvm:

     # replace 12 as needed
     ln -s $(which llvm-config-12) /usr/bin/llvm

• install nodejs 8.11 or newer

    curl -sL https://deb.nodesource.com/setup_lts.x | bash -
    apt install nodejs

• install nasm 2.14 (or better, but we go for the min):

    wget https://www.nasm.us/pub/nasm/releasebuilds/2.14/nasm-2.14.tar.xz
    tar xvf nasm-2.14.tar.xz; cd nasm-2.14

• open the Makefile in the nasm directory with a text editor, remove -Werror=attributes, save, then

    configure; make; make install

Make your modifications

• [∞] Return to the tor-browser directory, and hack away!

Generating configure, compiling and packaging

• [~1 min] generate configuration

  ./mach configure \
     --with-tor-browser-version=tbb-nightly \
     --with-distribution-id=org.torproject \
     --enable-update-channel=default \
     --enable-bundled-fonts

• [~80 min] Build

  ./mach build

• [<1 min] Package

  ./mach build stage-package

Getting an existing TBB to serve as a base

• create the base directory for the tor browser bundle (TBB) that we'll use as a base

    cd $HOME; mkdir tbb-to-copy-over; cd $_

• get the TBB; expand it

    wget https://www.torproject.org/dist/torbrowser/10.5a15/tor-browser-linux64-10.5a15_en-US.tar.xz
    wget https://www.torproject.org/dist/torbrowser/10.5a15/tor-browser-linux64-10.5a15_en-US.tar.xz.asc  # detached sig
    gpg --recv-key 0xEF6E286DDA85EA2A4BA7DE684E2C6E8793298290  # Tor Devs' signing key
    gpg --verify tor-browser-linux64-10.5a15_en-US.tar.xz.asc
    tar xvf tor-browser-linux64-10.0a6_en-US.tar.xz

• set an environment variable to make next steps easier

    export INSTDIR="$HOME/tbb-to-copy-over/tor-browser_en-US"

• Copy custom stuff onto this base

    cd ../tor-browser
    cp -a obj-*/dist/firefox/* $INSTDIR/Browser/

Make things smaller to aid transfer

• Remove symbols from the object files

    strip --strip-all $INSTDIR/Browser/*

• Remove unnecessary bits

    rm -f $INSTDIR/Browser/firefox-bin

Get the goodz on your local machine

Last, use rsync or whatever to get tbb-to-copy-over onto your local machine (below replace '${path-to-the-parent-of-tor-browser-dir}' with the path to the parent of the tor-browser directory on your server).

    rsync -avz --progress name-of-the-tor-build-server-you-set-up:${path-to-the-parent-of-tor-browser-dir}/tbb-to-copy-over .