Panoramica

libsignal contiene API indipendenti dalla piattaforma utilizzate dai client e dai server ufficiali di Signal, esposte come libreria Java, Swift o TypeScript. Le implementazioni sottostanti sono scritte in Rust:

• libsignal-protocol: implementa il protocollo Signal, incluso l'[algoritmo Double Ratchet][]. Un sostituto di libsignal-protocol-java e libsignal-metadata-java.
• signal-crypto: primitive crittografiche come AES-GCM. Utilizziamo quelle di RustCrypto dove possibile, ma a volte abbiamo esigenze diverse.
• device-transfer: logica di supporto per la funzionalità di trasferimento da dispositivo a dispositivo di Signal.
• attest: funzionalità per l'attestazione remota di [enclave SGX][] e [HSM][] lato server.
• zkgroup: funzionalità per i [gruppi a conoscenza zero][] e le funzionalità correlate disponibili in Signal.
• zkcredential: un'astrazione per il tipo di credenziali a conoscenza zero utilizzate da zkgroup, basata sul paper "The Signal Private Group System" di Chase, Perrin e Zaverucha.
• poksho: utilità per implementare prove a conoscenza zero (come quelle usate da zkgroup); sta per "proof-of-knowledge, stateful-hash-object".
• account-keys: funzionalità per utilizzare in modo coerente i [PIN][] come password nel sistema Secure Value Recovery di Signal, nonché altre operazioni su chiavi a livello di account.
• usernames: funzionalità per la generazione, l'hashing e le prove relative ai nomi utente.
• media: utilità per la manipolazione di contenuti multimediali.

Questo repository è utilizzato dalle app client di Signal (Android, iOS e Desktop) nonché lato server. L'uso al di fuori di Signal non è supportato. In particolare, i prodotti di questo repository sono le librerie Java, Swift e TypeScript che avvolgono le implementazioni Rust sottostanti. Tutte le API e le implementazioni sono soggette a modifiche senza preavviso, così come i livelli "bridge" JNI, C e add-on Node. Tuttavia, le modifiche retroincompatibili alle API Java, Swift, TypeScript e Rust non-bridge saranno riflesse nel numero di versione su base best-effort, incluse le variazioni alle versioni minime supportate degli strumenti.

Compilazione

Installazione della toolchain

Per compilare qualsiasi cosa in questo repository è necessario avere Rust installato, così come versioni recenti di Clang, libclang, CMake, Make, protoc, Python (3.9+) e git.

Linux/Debian

Su un sistema simile a Debian, puoi ottenere queste dipendenze aggiuntive tramite apt:

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

macOS

Su macOS, abbiamo uno script mantenuto con il miglior sforzo possibile per configurare la toolchain di Rust che puoi eseguire con:

$ bin/mac_setup.sh

Rust

Prima build e test

La build attualmente utilizza una versione specifica del compilatore Rust stable, che verrà scaricata automaticamente da cargo. Per compilare e testare le librerie di protocollo di base:

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

Strumenti Rust aggiuntivi

Gli strumenti di base sopra dovrebbero essere sufficienti per la maggior parte dello sviluppo Rust con libsignal.

Con il tempo, potresti scoprire di aver bisogno di alcuni strumenti Rust aggiuntivi come taplo per la formattazione del codice.

Dovresti sempre installare tramite cargo qualsiasi strumento Rust di cui hai bisogno che possa influire sulla build, piuttosto che dal gestore di pacchetti di sistema (ad esempio apt o brew). I gestori di pacchetti a volte contengono versioni obsolete di questi strumenti che possono compromettere la build con problemi di incompatibilità.

Per installare le principali dipendenze Rust aggiuntive corrispondenti alle versioni che utilizziamo, puoi eseguire i seguenti comandi:

$ 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

Configurazione/Setup della Toolchain

Per compilare per Android è necessario installare diversi pacchetti aggiuntivi, tra cui un JDK, l'Android NDK/SDK, e aggiungere i target Android al compilatore Rust, usando

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.

Building and Testing

To build the Java/Android jar and aar, and run the tests:

$ cd java
$ ./gradlew test
$ ./gradlew build # se hai bisogno di output AAR

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 cargo run -p libsignal-jni-native_kt (or just generate-jni) in addition to rebuilding.

Use as a library

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"
  // La parte "uri()" è necessaria solo per Kotlin Gradle; Groovy Gradle accetta una stringa semplice qui.
  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.

Testing a local build with Signal-Android