Überblick

libsignal enthält plattformunabhängige APIs, die von den offiziellen Signal-Clients und -Servern verwendet werden und als Java-, Swift- oder TypeScript-Bibliothek bereitgestellt werden. Die zugrunde liegenden Implementierungen sind in Rust geschrieben:

• libsignal-protocol: Implementiert das Signal-Protokoll, einschließlich des Double Ratchet algorithm. Ein Ersatz für libsignal-protocol-java und libsignal-metadata-java.
• signal-crypto: Kryptografische Primitive wie AES-GCM. Wir verwenden RustCryptos, wo wir können, haben aber manchmal abweichende Anforderungen.
• device-transfer: Unterstützungslogik für Signals Gerät-zu-Gerät-Übertragungsfunktion.
• attest: Funktionalität für Remote-Attestierung von SGX enclaves und serverseitigen HSMs.
• zkgroup: Funktionalität für zero-knowledge groups und verwandte Funktionen, die in Signal verfügbar sind.
• zkcredential: Eine Abstraktion für die Art von Zero-Knowledge-Credentials, die von zkgroup verwendet werden, basierend auf dem Paper "The Signal Private Group System" von Chase, Perrin und Zaverucha.
• poksho: Hilfsprogramme zur Implementierung von Zero-Knowledge-Beweisen (wie denen, die von zkgroup verwendet werden); steht für "proof-of-knowledge, stateful-hash-object".
• account-keys: Funktionalität für die konsistente Verwendung von PINs als Passwörter in Signals Secure Value Recovery-System sowie für andere kontoweite Schlüsseloperationen.
• usernames: Funktionalität für Benutzernamengenerierung, Hashing und Proofs.
• media: Hilfsprogramme zur Bearbeitung von Medien.

Dieses Repository wird von den Signal-Client-Apps (Android, iOS und Desktop) sowie serverseitig verwendet. Die Verwendung außerhalb von Signal wird nicht unterstützt. Insbesondere sind die Produkte dieses Repositorys die Java-, Swift- und TypeScript-Bibliotheken, die die zugrunde liegenden Rust-Implementierungen umhüllen. Alle APIs und Implementierungen können ohne Vorankündigung geändert werden, ebenso wie die JNI-, C- und Node-Add-on- "Bridge"-Schichten. Rückwärtsinkompatible Änderungen an den Java-, Swift-, TypeScript- und Nicht-Bridge-Rust-APIs werden jedoch nach bestem Bemühen in der Versionsnummer widergespiegelt, einschließlich Erhöhungen der minimal unterstützten Tool-Versionen.

Erstellen

Installation der Toolchain

Um irgendetwas in diesem Repository zu erstellen, müssen Sie Rust installiert haben, sowie aktuelle Versionen von Clang, libclang, CMake, Make, protoc, Python (3.9+) und git.

Linux/Debian

Auf einem Debian-ähnlichen System können Sie diese zusätzlichen Abhängigkeiten über apt erhalten:

$ apt-get install clang libclang-dev cmake make protobuf-compiler libprotobuf-dev python3 git

macOS

Auf macOS haben wir ein nach bestem Bemühen gepflegtes Skript zur Einrichtung der Rust-Toolchain, das Sie ausführen können mit:

$ bin/mac_setup.sh

Rust

Erster Build und Test

Der Build verwendet derzeit eine bestimmte Version des stabilen Rust-Compilers, die automatisch von cargo heruntergeladen wird. Um die grundlegenden Protokoll- Bibliotheken zu erstellen und zu testen:

$ cargo build
...
$ cargo test
...

Zusätzliche Rust-Tools

Die grundlegenden Tools oben sollten Sie für die meisten libsignal-Rust-Entwicklungen einrichten.

Mit der Zeit werden Sie möglicherweise feststellen, dass Sie einige zusätzliche Rust-Tools wie taplo für die Codeformatierung benötigen.

Sie sollten alle Rust-Tools, die Sie benötigen und die den Build beeinflussen könnten, immer von cargo und nicht von Ihrem System- Paketmanager (z. B. apt oder brew) installieren. Paketmanager enthalten manchmal veraltete Versionen dieser Tools, die den Build mit Inkompatibilitätsproblemen brechen können (insbesondere cbindgen).

Um die wichtigsten zusätzlichen Rust-Abhängigkeiten passend zu den von uns verwendeten Versionen zu installieren, können Sie die folgenden Befehle ausführen:

$ 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

Java/Android

Einrichtung / Konfiguration der Toolchain

Um für Android zu erstellen, müssen Sie mehrere zusätzliche Pakete installieren, darunter ein JDK, das Android NDK/SDK, und die Android-Ziele zum Rust-Compiler hinzufügen, mit

rustup target add armv7-linux-androideabi aarch64-linux-android i686-linux-android x86_64-linux-android

Unsere offiziell unterstützte JDK-Version für Android-Builds ist JDK 21, stellen Sie also sicher, dass Sie z. B. OpenJDK 21 installieren und dann JAVA_HOME darauf verweisen.

Auf macOS können Sie dies einfach tun über:

export JAVA_HOME=$(/usr/libexec/java_home -v 21)

Unter Linux variiert die Vorgehensweise je nach Distribution. Für Debian-basierte Distributionen wie Ubuntu können Sie verwenden:

sudo update-alternatives --config java

Wir checken außerdem eine .tools_version-Datei zur Verwendung mit Laufzeit-Versionsmanagern ein.

Erstellen und Testen

Um das Java/Android-jar und aar zu erstellen und die Tests auszuführen:

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

Sie können -P debugLevelLogs an Gradle übergeben, um ohne Herausfiltern von Debug- und Verbose-Level- Logs aus Rust zu erstellen, und -P jniTypeTagging, um zusätzliche Prüfungen im Rust-JNI-Bridging-Code zu aktivieren.

Alternativ steht ein Build-System mit Docker zur Verfügung:

$ cd java
$ make

Wenn Sie neue APIs für Java bereitstellen, müssen Sie zusätzlich zum Neuerstellen rust/bridge/jni/bin/gen_java_decl.py ausführen. Dies erfordert die Installation des cbindgen-Rust-Tools, wie oben beschrieben.

Verwendung als Bibliothek

Signal veröffentlicht Java-Pakete für den eigenen Gebrauch unter den Namen org.signal:libsignal-server, org.signal:libsignal-client und org.signal:libsignal-android. libsignal-client und libsignal-server enthalten native Bibliotheken für Debian-basiertes x86_64 Linux sowie Windows (x86_64) und macOS (x86_64 und arm64). libsignal-android enthält native Bibliotheken für armeabi-v7a, arm64-v8a, x86 und x86_64 Android. Diese befinden sich in einem Maven-Repository unter https://build-artifacts.signal.org/libraries/maven/; für die Verwendung von Gradle aus fügen Sie Folgendes zu Ihrem repositories-Block hinzu:

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/")
}

Ältere Builds wurden stattdessen auf Maven Central veröffentlicht.

Beim Erstellen für Android benötigen Sie sowohl libsignal-android als auch libsignal-client, aber die Windows- und macOS-Bibliotheken in libsignal-client werden nicht automatisch aus Ihrer endgültigen App ausgeschlossen. Sie können sie explizit mit packaging ausschließen: