Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/katya-incorporated/dvpn

Calyx VPN & dVPN for Katya ® 👽 OS
https://github.com/katya-incorporated/dvpn

dvpn dvpn-client dvpn-dashboard vpn vpn-client vpn-server

Last synced: 8 days ago
JSON representation

Calyx VPN & dVPN for Katya ® 👽 OS

Awesome Lists containing this project

README

        

# Bitmask Android Client

This repository contains the source code for the [Bitmask](https://bitmask.net/) 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](https://leap.se).

Please see the [issues](https://0xacab.org/leap/bitmask_android/issues) section to report any bugs or feature requests, and to see the list of known issues.

# Table Of Contents

* [License](#license)
* [Installing](#installing)
* [JDK](#jdk)
* [C Libraries](#c-libraries)
* [Android SDK](#android-sdk)
* [With Android Studio](#with-android-studio)
* [With Bash](#with-bash)
* [Updating Your PATH](#updating-your-path)
* [With Docker](#with-docker)
* [Submodules](#submodules)
* [Compiling](#compiling)
* [Just Build It!](#just-build-it)
* [Debug APKs](#debug-apks)
* [Release APKs](#release-apks)
* [Signed Release APKs](#signed-release-apks)
* [Localization](#localize)
* [Supported Versions](#supported-versions)
* [Acknowledgments](#acknowledgments)
* [Contributing](#contributing)

## License

* [See LICENSE file](https://github.com/leapcode/bitmask_android/blob/master/LICENSE.txt)

## 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 11
* Android SDK Tools, v. 30.0.3, with these packages:
* Platform-Tools, v. 30.0.3
* Build-Tools, API v. 30
* Platforms 30
* 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:

```bash
sudo apt-get update -qq && \
apt-get install -y openjdk-11-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](/docker/)

#### 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`:

```shell
export ANDROID_HOME=
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](/docker/android-sdk/Dockerfile) and [android-ndk Dockerfile](/docker/android-ndk/Dockerfile) itself for requirements that your system might need but be missing.

Assuming you've already [installed docker](https://docs.docker.com/engine/installation/), you can pull the image with:

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

Run the image with:

``` shell
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:

``` shell
cd
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](https://git-scm.com/book/en/v2/Git-Tools-Submodules) to build Bitmask Android:
* [ics-openvpn](https://github.com/schwabe/ics-openvpn) as an interface to Android's OpenVPN implementation.
* [bitmaskcore](https://0xacab.org/leap/android_libs/bitmaskcore.git) mainly as a library for Pluggable Transports (censorship circumvention functionality),
* [tor-android](https://0xacab.org/leap/android_libs/tor-android.git) to protect the communication to configuration servers from being blocked.
In order to initialize and update these submodules run:

```bash
cd
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](/docker/android-sdk/Dockerfile) and [android-ndk Dockerfile](/docker/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
```

### Debug APKs

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

In order to build a custom branded version of Bitmask you can run:
```bash
./gradlew assembleCustomProductionFatDebug
```

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](/scripts/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:
```bash
./scripts/prepareForDistribution.sh build sign -ks ~/path/to/bitmask-android.keystore -ka
```

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:

```bash
./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 16 (Android 4.1) - API 30 (Android 11) 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](https://code.google.com/p/ics-openvpn/).

## Reporting Bugs
Please file bug tickets on our main [development platform](https://0xacab.org/leap/bitmask_android/issues). 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](https://0xacab.org/leap/bitmask_android/merge_requests).

Our preferred method for receiving translations is our [Transifex project](https://www.transifex.com/otf/bitmask). Localization Lab helps us with on-boarding volunteers. If you are new to translations and Transifex we've got a [short how-to](https://wiki.localizationlab.org/index.php/Bitmask).

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.