Bitmask Android Client

This repository contains the source code for the Bitmask Android client. Bitmask Android offers one-click free VPN service from trusted providers of the LEAP stack.

To learn about the stack, visit leap.se.

Please see the issues section to report any bugs or feature requests, and to see the list of known issues.

Table Of Contents

• License
• Installing
  • JDK
  • C Libraries
  • Android SDK
    • With Android Studio
    • With Bash
    • Updating Your PATH
    • With Docker
  • Submodules
• Compiling
  • Just Build It!
  • Debug APKs
  • Release APKs
  • Signed Release APKs
  • Localization
• Supported Versions
• Acknowledgments
• Contributing

License

• See LICENSE file

Installing

We will assume for convenience that you are installing on a Debian- or Ubuntu-based GNU/Linux machine. (Patches welcome with instructions for Mac, Windows, or other GNU/Linux distributions!)

The Bitmask Android Client has the following system-level dependencies:

• JDK 17
• Android SDK Tools, v. 34.0.3, with these packages:
  • Platform-Tools, v. 34.0.5
  • Build-Tools, API v. 34
  • Platforms 34
  • Android Support Repository
  • Google Support Repository
  • NDK v. r21e (enables C code in Android)
• For running the app in an emulator, you will also need these packages:
  • Android Emulator
  • System Images for Android APIs 30
• ics-openvpn submodule
• tor-android submodule
• bitmaskcore submodule

You can install them as follows:

JDK

Install with:

sudo apt-get update -qq && \
    apt-get install -y openjdk-17-jdk

C Libraries

These are necessary to make sure the program cross-compiles openssl, openvpn, tor etc. for Bitmask Android.

sudo apt-get -y install make gcc swig file lib32stdc++6 lib32z1 autoconf autogen automake autopoint autotools-dev gettext-base libtool patch pkg-config mesa-utils

Android SDK

With Android Studio

All of the Android SDK and NDK packages are downloadable through Android Studio, which (sadly) is probably the most hassle-free way to go about things.

You can download Android studio here:

https://developer.android.com/studio/index.html

Once you've got it installed, use the SDK Manager tool (Android figure Icon with blue arrow second from the right in the tool pane) to download all the Android SDK and NDK dependencies listed above.

With Bash

Alternatively (eg: for build machines), you may have a look at our docker build files in the docker directory

Updating Your Path

Once you've installed Android SDK & NDK packages, you need to modify your PATH so you can invoke all the programs you just installed. You can do that with something like the following in your ~/.shellrc or ~/.bash_profile:

export ANDROID_HOME=<path/where/you/installed/android/sdk>
export ANDROID_NDK_HOME=$ANDROID_HOME/ndk/21.4.7075529
export PATH=$ANDROID_NDK_HOME:$PATH
export PATH=$ANDROID_HOME/platform-tools:$PATH
export PATH=$ANDROID_HOME/tools/bin:$PATH

With Docker

Geesh! If all that above seems like a lot, it is!

To keep ourselves from messing it up all the time someone new joins the project, we made a Dockerfile that creates the above environment with one line. You can pull the image and run builds from inside it, or consult android-sdk Dockerfile and android-ndk Dockerfile itself for requirements that your system might need but be missing.

Assuming you've already installed docker, you can pull the image with:

docker pull registry.0xacab.org/leap/bitmask_android/android-ndk:latest

Run the image with:

docker run --rm -it registry.0xacab.org/leap/bitmask_android/android-ndk:latest

More likely than not, you'll want to run the image with the source code mounted. You can do that with:

cd <path/to/bitmask_android>
docker run --rm -it -v`pwd`:/bitmask_android -t registry.0xacab.org/leap/bitmask_android/android-ndk:latest

Submodules

We depend on several git submodules to build Bitmask Android:

• ics-openvpn as an interface to Android's OpenVPN implementation.
• bitmaskcore mainly as a library for Pluggable Transports (censorship circumvention functionality),
• tor-android to protect the communication to configuration servers from being blocked. In order to initialize and update these submodules run:

cd <path/to/bitmask_android>
git submodule init
git submodule update --init --recursive

Compiling

Just Build It!

If you compile the project for the first time you'll have to compile the dependencies. In order to get a clean build and fetch all submodules run:

./scripts/cleanProject.sh

The following command will create all libs we need for Bitmask.

./scripts/build_deps.sh

If you run into errors, you may miss some dependencies on your system. Again, please check the RUN apt-get commands of android-sdk Dockerfile and android-ndk Dockerfile to get an idea what might be missing. Please note that tor-android can only be build on Linux machines right now. Fixes for Windows and MacOS are more than welcome! In order to temporarily disable building tor you can run:

BUILD_TOR=false ./scripts/build_deps.sh

Custom Builds

Please refer to to the customization README.

Debug APKs

After having run ./build_deps.sh, you can assemble debug packages for running locally or testing in CI:

./gradlew assembleNormalProductionFatDebug

If everything went fine, you will find the debug apks in /bitmask_android/app/build/outputs/apk/.

Release APKs

To build releases, a script comes to the rescue: prepareForDistribution.sh `

Before you can actually build a release make sure you have setup a keystore with your Android signing key. Additionally you can sign your software with your PGP key using this script.

If you want to build and sign apks and aab bundles for the current commit, run:

  ./scripts/prepareForDistribution.sh build sign -ks ~/path/to/bitmask-android.keystore -ka <yourKeystoreKeyAlias>

Please check ./prepareFordistribution.sh -h for all options!

Running unit tests

Unit tests should always run against release builds, it is expected that some tests fail in debug builds.

You can execute all unit tests from the command line with:

  ./gradlew testCustomProductionFatReleaseUnitTest testNormalProductionFatReleaseUnitTest

Localization and translate

All the localizations happen in Transifex. How to generate, push, pull the translations are detailed in src/README.md

Supported Versions

Currently API 21 (Android 5.0) - API 34 (Android 14) are officially supported. Keep backwards compatibility in mind if you plan to contribute new features.

Acknowledgments

This project bases its work in ics-openvpn project.

Reporting Bugs

Please file bug tickets on our main development platform. You can either create an account on 0xacab.org or simply login with your github.com or gitlab.com account to create new tickets.

Contributing

Please fork this repository and contribute back using pull requests.

Our preferred method for receiving translations is our Transifex project. Localization Lab helps us with on-boarding volunteers. If you are new to translations and Transifex we've got a short how-to.

Any contributions, large or small, major features, bug fixes, additional language translations, unit/integration tests are welcomed and appreciated but will be thoroughly reviewed and discussed.