Repository files navigation

libsignal contains platform-agnostic APIs used by the official Signal clients and servers, exposedas a Java, Swift, or TypeScript library. The underlying implementations are written in Rust:

• libsignal-protocol: Implements the Signal protocol, including theDouble Ratchet algorithm. Areplacement forlibsignal-protocol-java andlibsignal-metadata-java.
• signal-crypto: Cryptographic primitives such as AES-GCM. We useRustCrypto's where we canbut sometimes have differing needs.
• device-transfer: Support logic for Signal's device-to-device transfer feature.
• attest: Functionality for remote attestation ofSGX enclaves and server-sideHSMs.
• zkgroup: Functionality forzero-knowledge groups and related features available in Signal.
• zkcredential: An abstraction for the sort of zero-knowledge credentials used by zkgroup, based on the paper "The Signal Private Group System" by Chase, Perrin, and Zaverucha.
• poksho: Utilities for implementing zero-knowledge proofs (such as those used by zkgroup); stands for "proof-of-knowledge, stateful-hash-object".
• account-keys: Functionality for consistently usingPINs as passwords in Signal's Secure Value Recovery system, as well as other account-wide key operations.
• usernames: Functionality for username generation, hashing, and proofs.
• media: Utilities for manipulating media.

This repository is used by the Signal client apps (Android,iOS, andDesktop) as well asserver-side. Use outside of Signal is unsupported. In particular, the products of this repositoryare the Java, Swift, and TypeScript libraries that wrap the underlying Rust implementations. AllAPIs 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, andnon-bridge Rust APIs will be reflected in the version number on a best-effort basis, includingincreases to the minimum supported tools versions.

To build anything in this repository you must haveRust installed,as well as Clang, libclang,CMake, Make, protoc, and git.

On a Debian-like system, you can get these extra dependencies throughapt:

$ apt-get install clang libclang-dev cmake make protobuf-compiler 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 nightly compiler, whichwill be downloaded automatically by cargo. To build and test the basic protocollibraries:

$ cargo build...$ cargotest...

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 likecbindgen to modify the bridges to theclient libraries ortaplo for code formatting.

You should always install any Rust tools you need that may affect the build from cargo rather than from your systempackage manager (e.g.apt orbrew). Package managers sometimes contain outdated versions of these tools that can breakthe 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 cbindgen cargo-fuzz$ cargo +stable install --version"$(cat ../acknowledgments/cargo-about-version)" --locked cargo-about$ cargo +stable install --version"$(cat ../.taplo-cli-version)" --locked taplo-cli

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

To build the Java/Androidjar andaar, and run the tests:

$cd java$ ./gradlewtest$ ./gradlew build# if you need AAR outputs

You can pass-P debugLevelLogs to Gradle to build without filtering out debug- and verbose-levellogs from Rust.

Alternately, a build system using Docker is available:

$cd java$ make

When exposing new APIs to Java, you will need to runrust/bridge/jni/bin/gen_java_decl.py inaddition to rebuilding. This requires installing thecbindgen Rust tool, as detailed above.

Signal publishes Java packages onMaven Central for its own use,under the names org.signal:libsignal-server, org.signal:libsignal-client, andorg.signal:libsignal-android. libsignal-client and libsignal-server contain native libraries forDebian-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.

When building for Android you needboth libsignal-android and libsignal-client, but the Windowsand macOS libraries in libsignal-client won't automatically be excluded from your final app. You canexplicitly exclude them usingpackagingOptions:

android {  // ...  packagingOptions {    resources {      excludes += setOf("libsignal_jni*.dylib", "signal_jni*.dll")    }  }  // ...}

You can additionally excludelibsignal_jni_testing.so if you do not plan to use any of the APIsintended for client testing.

To learn about the Swift build process seeswift/README.md

You'll need Node installed to build. If you havenvm, you can runnvm use to select anappropriate version automatically.

We usenpm as our package manager, andnode-gyp to control building the Rust library.

$cd node$ nvm use$ npm install$ npx node-gyp rebuild# clean->configure->build$ npm run tsc$ npm runtest

When testing changes locally, you can usenpm run build to do an incremental rebuild of the Rust library. Alternately,npm run build-with-debug-level-logs will rebuild without filtering out debug- and verbose-level logs.

When exposing new APIs to Node, you will need to runrust/bridge/node/bin/gen_ts_decl.py inaddition to rebuilding.

Signal publishes the NPM package@signalapp/libsignal-client for its own use, including nativelibraries for Windows, macOS, and Debian-flavored Linux. Both x64 and arm64 builds are included forall three platforms, but the arm64 builds for Windows and Linux are considered experimental, sincethere are no official builds of Signal for those architectures.

Signal does accept external contributions to this project. However unless the change issimple and easily understood, for example fixing a bug or portability issue, adding a newtest, or improving performance, first open an issue to discuss your intended change as notall changes can be accepted.

Contributions that will not be used directly by one of Signal's official client apps may still beconsidered, but only if they do not pose an undue maintenance burden or conflict with the goals ofthe project.

Signing aCLA (Contributor License Agreement) is required for all contributions.

You can run the styler on the entire project by running:

just format-all

You can run more extensive tests as well as linters and clippy by running:

just check-pre-commit

When making a PR that adjusts dependencies, you'll need to regenerate our acknowledgments files. Seeacknowledgments/README.md.

This distribution includes cryptographic software. The country in which you currently reside may have restrictions onthe import, possession, use, and/or re-export to another country, of encryption software. BEFORE using any encryptionsoftware, please check your country's laws, regulations and policies concerning the import, possession, or use, andre-export of encryption software, to see if this is permitted. Seehttp://www.wassenaar.org/ for more information.

The U.S. Government Department of Commerce, Bureau of Industry and Security (BIS), has classified this software asExport Commodity Control Number (ECCN) 5D002.C.1, which includes information security software using or performingcryptographic functions with asymmetric algorithms. The form and manner of this distribution makes it eligible forexport under the License Exception ENC Technology Software Unrestricted (TSU) exception (see the BIS ExportAdministration Regulations, Section 740.13) for both object code and source code.

Copyright 2020-2024 Signal Messenger, LLC

Licensed under the GNU AGPLv3:https://www.gnu.org/licenses/agpl-3.0.html