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. Usiamo 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 usate da zkgroup, basata sull'articolo "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 usare 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 dei media.

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 retro-incompatibili 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 devi avere Rust installato, oltre a 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 su base best-effort per configurare la toolchain Rust che puoi eseguire con:

$ bin/mac_setup.sh

Rust

Prima compilazione 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 di libsignal.

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

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

Per installare le principali dipendenze Rust extra corrispondenti alle versioni che usiamo, 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 della toolchain

Per compilare per Android devi 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

La nostra versione JDK ufficialmente supportata per le build Android è JDK 21, quindi assicurati di installare ad es. OpenJDK 21, e poi punta JAVA_HOME ad esso.

Puoi farlo facilmente su macOS tramite:

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

Su Linux, il modo in cui lo fai varia a seconda della distribuzione. Per distribuzioni basate su Debian come Ubuntu, puoi usare:

sudo update-alternatives --config java

Inoltre, effettuiamo il check-in di un file .tools_version per l'uso con i gestori di versione runtime.

Compilazione e test

Per compilare il jar e l'aar Java/Android, ed eseguire i test:

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

Puoi passare -P debugLevelLogs a Gradle per compilare senza filtrare i log di livello debug e verbose da Rust, e -P jniTypeTagging per abilitare controlli aggiuntivi nel codice di bridging JNI Rust.

In alternativa, è disponibile un sistema di build che utilizza Docker:

$ cd java
$ make

Quando esponi nuove API a Java, dovrai eseguire rust/bridge/jni/bin/gen_java_decl.py in aggiunta alla ricompilazione. Questo richiede l'installazione dello strumento Rust cbindgen, come dettagliato sopra.

Uso come libreria

Signal pubblica pacchetti Java per uso proprio, con i nomi org.signal:libsignal-server, org.signal:libsignal-client e org.signal:libsignal-android. libsignal-client e libsignal-server contengono librerie native per Linux x86_64 in stile Debian, nonché Windows (x86_64) e macOS (x86_64 e arm64). libsignal-android contiene librerie native per armeabi-v7a, arm64-v8a, x86 e x86_64 Android. Queste si trovano in un repository Maven all'indirizzo https://build-artifacts.signal.org/libraries/maven/; per l'uso da Gradle, aggiungi quanto segue al tuo blocco repositories:

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

Le build precedenti erano pubblicate su Maven Central.

Quando compili per Android hai bisogno sia di libsignal-android che di libsignal-client, ma le librerie Windows e macOS in libsignal-client non verranno automaticamente escluse dalla tua app finale. Puoi escluderle esplicitamente usando packaging:

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

Puoi inoltre escludere libsignal_jni_testing.so se non prevedi di usare nessuna delle API destinate ai test del client.

Testare una build locale con Signal-Android