
Home to the Signal Protocol as well as other cryptographic primitives which make Signal possible.
libsignal contains platform-agnostic APIs used by the official Signal clients and servers, exposed as a Java, Swift, or TypeScript library. The underlying implementations are written in Rust:
This repository is used by the Signal client apps (Android, iOS, and Desktop) as well as server-side. Use outside of Signal is unsupported. In particular, the products of this repository are the Java, Swift, and TypeScript libraries that wrap the underlying Rust implementations. All APIs and implementations are subject to change without notice, as are the JNI, C, and Node add-on "bridge" layers. However, backwards-incompatible changes to the Java, Swift, TypeScript, and non-bridge Rust APIs will be reflected in the version number on a best-effort basis, including increases to the minimum supported tools versions.
To build anything in this repository you must have Rust installed, as well as recent versions of Clang, libclang, CMake, Make, protoc, Python (3.9+), and git.
On a Debian-like system, you can get these extra dependencies through apt:
$ apt-get install clang libclang-dev cmake make protobuf-compiler libprotobuf-dev python3 git
On macOS, we have a best-effort maintained script to set up the Rust toolchain you can run by:
$ bin/mac_setup.sh
The build currently uses a specific version of the Rust stable compiler, which will be downloaded automatically by cargo. To build and test the basic protocol libraries:
$ cargo build
...
$ cargo test
...
The basic tools above should get you set up for most libsignal Rust development.
Eventually, you may find that you need some additional Rust tools like taplo for code formatting.
You should always install any Rust tools you need that may affect the build from cargo rather than from your system
package manager (e.g. apt or brew). Package managers sometimes contain outdated versions of these tools that can break
the build with incompatibility issues (especially cbindgen).
To install the main Rust extra dependencies matching the versions we use, you can run the following commands:
$ cargo +stable install --version "$(cat acknowledgments/cargo-about-version)" --locked cargo-about
$ cargo +stable install --version "$(cat .taplo-cli-version)" --locked taplo-cli
$ cargo +stable install cargo-fuzz
To build for Android you must install several additional packages including a JDK, the Android NDK/SDK, and add the Android targets to the Rust compiler, using
rustup target add armv7-linux-androideabi aarch64-linux-android i686-linux-android x86_64-linux-android
Our officially supported JDK version for Android builds is JDK 21, so be sure to install e.g. OpenJDK 21, and then point JAVA_HOME to it.
You can easily do this on macOS via:
export JAVA_HOME=$(/usr/libexec/java_home -v 21)
On Linux, the way you do this varies by distribution. For Debian based distributions like Ubuntu, you can use:
sudo update-alternatives --config java
We also check-in a .tools_version file for use with runtime version managers.
To build the Java/Android jar and aar, and run the tests:
$ cd java
$ ./gradlew test
$ ./gradlew build # if you need AAR outputs
You can pass -P debugLevelLogs to Gradle to build without filtering out debug- and verbose-level
logs from Rust, and -P jniTypeTagging to enable additional checks in the Rust JNI bridging code.
Alternately, a build system using Docker is available:
$ cd java
$ make
When exposing new APIs to Java, you will need to run rust/bridge/jni/bin/gen_java_decl.py in
addition to rebuilding. This requires installing the cbindgen Rust tool, as detailed above.
Signal publishes Java packages for its own use, under the names org.signal:libsignal-server,
org.signal:libsignal-client, and org.signal:libsignal-android. libsignal-client and libsignal-server
contain native libraries for Debian-flavored x86_64 Linux as well as Windows (x86_64) and macOS
(x86_64 and arm64). libsignal-android contains native libraries for armeabi-v7a, arm64-v8a, x86, and
x86_64 Android. These are located in a Maven repository at
https://build-artifacts.signal.org/libraries/maven/; for use from Gradle, add the following to your
repositories block:
maven {
name = "SignalBuildArtifacts"
// The "uri()" part is only necessary for Kotlin Gradle; Groovy Gradle accepts a bare string here.
url = uri("https://build-artifacts.signal.org/libraries/maven/")
}
Older builds were published to Maven Central instead.
When building for Android you need both libsignal-android and libsignal-client, but the Windows
and macOS libraries in libsignal-client won't automatically be excluded from your final app. You can
explicitly exclude them using packaging:
android {
// ...
packaging {
resources {
excludes += setOf("libsignal_jni*.dylib", "signal_jni*.dll")
}
}
// ...
}
You can additionally exclude libsignal_jni_testing.so if you do not plan to use any of the APIs
intended for client testing.