Open Source

Overview

Source Code and Documentation

Mobile Apps

• Threema for Android

• Threema for iOS

Desktop App / Threema Web

• Threema 1.x for desktop: The app for macOS, Windows, and Linux

• Threema 2.0 for desktop (beta): The next-generation desktop app for macOS, Windows, and Linux

• Threema Web: The Threema Web application

• Push Relay: Push notifications for Threema Web

• Compose Area: Library for a compose area with support for inline images

• App Remote Protocol: Documentation of the Threema Web protocol

Build Instructions

Build and test instructions can be found in the README files included in the source-code repositories.

Reproducible Builds

In order to verify that the published source code actually matches the source code the mobile apps in the stores were built with, we provide reproducible builds.

At the moment, reproducible builds are available for Threema’s Android app. Due to restrictions by Apple, it’s no easy task to offer reproducible builds for iOS, but we are currently evaluating possible ways to also support reproducible builds for this platform.

For instructions on how to reproduce the published Android app build, please refer to the Reproducible Builds page.

Bug Reports / Feature Requests / Security Issues

To report bugs or request new features, please contact the Threema support team.

If you discover a security issue in Threema, please adhere to the coordinated vulnerability disclosure model.

To be eligible for a bug bounty, please file a report on GObugfree (where all the details, including the bounty levels, are listed).

If you’re not interested in the bug bounty program, you can contact us via Threema or by email; for contact details, see threema.ch/contact (section “Security”).

Contributions

You can contribute to the Threema apps through pull requests on GitHub, after signing the Contributor License Agreement. Please refer to the Submitting Contributions page for more information. (To translate the Threema app, please don’t create a pull requests; contact our support to get added as community translator on Crowdin.)

License

The Threema apps are subject to the GNU Affero General Public License version 3. More details can be found in the source code repositories.

Please note that even though they may be compiled and modified freely, the Threema apps are still paid apps. An anonymous license check prevents the creation of Threema IDs on self-compiled apps. If you would like to use a self-compiled app, please restore the backup of an existing Threema ID. You can create Threema IDs and backups thereof using the purchased app.

If you have questions about the use of self-compiled apps or the license in general, feel free to contact us. We are publishing the source code in good faith, with transparency being the main goal. By having users pay for the development of the app, we can ensure that our goals sustainably align with the goals of our users: Great privacy and security, no ads, no collection of user data!

Reproducible Builds

In order to verify that the published source code was actually used to build the apps available for download in the stores, we provide reproducible builds.

Please note that Threema’s reproducible builds are still experimental. If a build cannot be reproduced, please let us know, and we’ll look into it.

Android

Prerequisites: A command line environment including bash, git, curl, gunzip and unzip as well as a Docker installation.

1. Determine App Version

In the Threema app on your phone, navigate to “Settings > About Threema,” and take note of the version. Export this information as well as the build variant (either googleplay, threemashop, libre or hms) into variables. For example, if you’re using the Google Play version of Threema 4.54 for Android:

$ export VERSION=4.54 VARIANT=googleplay

2. Extract the APK from Your Device

First, you need to extract the APK file from your phone. The recommended way to do this is by using Android Debug Bridge (adb) on a phone where Developer Mode is enabled. Run the following command:

$ export APP_ID=ch.threema.app
$ adb pull $(adb shell pm path $APP_ID | grep "/base.apk" | sed 's/^package://') threema-extracted.apk

(Note: For Threema Libre, the app ID must be ch.threema.app.libre and for the HMS version it must be ch.threema.app.hms.)

This will result in a file named threema-extracted.apk in your current directory.

There are also other ways to extract an APK file, e.g., by using backup apps or by means of a file manager on a rooted phone. How you obtain the APK is up to you.

Please note: If you use the Threema Shop version of Threema, you can also download the APK directly from the website instead of extracting it from your phone.

3. Load Docker Image

In order to reproduce the build, you need to load the Docker image containing the build environment that was used to generate the published app. The image can be downloaded from the Threema website.

$ cd /tmp
$ curl -LO https://oss.threema.ch/android/docker/docker-image-android-$VERSION.tar.gz
$ gunzip --stdout docker-image-android-$VERSION.tar.gz | docker image load

You can verify that the image was loaded properly by running docker image ls threema/android-compile.

4. Build Threema for Android

Next, you should compile Threema. First, clone the repository:

$ git clone https://github.com/threema-ch/threema-android
$ cd threema-android

Check out the tag corresponding to your app version.

$ git checkout $VERSION

Next, build the release APKs.

$ ./scripts/build-release.sh -v $VARIANT -n $VERSION --no-image-export --i-accept-the-android-sdk-license

This will result in an APK file at release/$VERSION/$VARIANT/.

5. Verify the Result

You can use the verify-build.sh script to verify the locally compiled APK against the extracted APK.

$ ./scripts/verify-build.sh -n $VERSION -v $VARIANT -p threema-extracted.apk
...
==> Comparing releases
==> Success! The APKs match.

If you get “Success” as log output, you have successfully verified that the app you have installed on your device corresponds to the published source code!

In case the verification fails, don’t panic! Please double-check that the version of the extracted APK corresponds to the source-code version you have checked out. If you are positive that this is correct, please send the log to opensource@threema.ch.

iOS

At the moment, reproducible builds are available for Threema’s Android app. Due to restrictions by Apple, it’s no easy task to offer reproducible builds for iOS, but we are currently evaluating possible ways to also support reproducible builds for this platform.

Contributing to Threema

You can contribute to the Threema apps through pull requests on GitHub. Please follow the steps below:

1. Preparation

If you want to make a larger change to the Threema apps, we recommend that you contact us first via e-mail to opensource@threema.ch to explain your plans. This way, we can give you early feedback about your idea, before you spend the time to actually implement the change.

Please mention the following:

• What you would like to implement

• How you would like to implement it

2. Sign the CLA

We require all contributors to sign our Contributor License Agreement (CLA) for non-trivial contributions. Please ensure that you have signed it before submitting a contribution.

Note that at all times you retain full ownership of your contributions. We only require a copyright license, not a copyright transfer.

3. Apply Your Changes to a Branch

Fork and clone the git repository you wish to modify.

$ git clone git@github.com:<your-user>/threema-<platform>.git

Create a new branch.

$ git checkout -b my-feature-or-fix

Apply your changes, test, and commit them.

4. Send a Pull Request

Once you are done, push your branch to GitHub and open a pull request.

Please understand that we cannot guarantee that we will accept your contribution. A bug may have already been fixed in our development version, a contribution may conflict with another contribution, or we may have other plans for Threema’s development. Nevertheless, you will hear back from us.