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

Il file gradle.properties di Signal-Android ha una riga commentata per includere libsignal come parte della build. Decommentala e regola il percorso; opzionalmente, puoi limitare le architetture per cui vuoi compilare aggiungendo androidArchs=aarch64 al gradle.properties di libsignal. (L'insieme delle architetture riconosciute è in java/build_jni.sh.) Se stai usando un IDE, dovrai reimportare la struttura Gradle a questo punto. Quando hai finito, ripristina le modifiche al gradle.properties dell'app Android e reimporta ancora una volta.

Nota che questo non importa le parti in Rust del progetto nell'IDE. Farlo in un IDE multi-linguaggio come IDEA è possibile, ma complicato; a partire dal 2025 il modo più affidabile per farlo è aprire prima il progetto Android, aggiungere la directory radice del repository libsignal come progetto Rust per secondo (includendo solo la directory di primo livello), e solo allora apportare le modifiche a gradle.properties.

Swift

Per informazioni sul processo di build Swift vedi swift/README.md

Node

Avrai bisogno di Node installato per compilare. Se hai nvm, puoi eseguire nvm use per selezionare automaticamente una versione appropriata.

Usiamo npm come gestore di pacchetti, e uno script Python per controllare la compilazione della libreria Rust, accessibile come npm run build.

$ cd node
$ nvm use
$ npm install
$ npm run build
$ npm run tsc
$ npm run test

Quando testi le modifiche localmente, puoi usare npm run build per fare una ricompilazione incrementale della libreria Rust. In alternativa, npm run build-with-debug-level-logs ricompilerà senza filtrare i log di livello debug e verbose.

Quando esponi nuove API a Node, dovrai eseguire just generate-node in aggiunta alla ricompilazione.

NPM

Signal pubblica il pacchetto NPM @signalapp/libsignal-client per uso proprio, incluse le librerie native per Windows, macOS e Linux in stile Debian. Sono incluse sia le build x64 che arm64 per tutte e tre le piattaforme, ma le build arm64 per Windows e Linux sono considerate sperimentali, poiché non esistono build ufficiali di Signal per quelle architetture.

Testare una build locale con Signal-Desktop

Dopo aver eseguito tutti i comandi di build sopra, modifica la dipendenza @signalapp/libsignal-client nel package.json dell'app Desktop in "link:path/to/libsignal/node" ed esegui pnpm install. Quando hai finito, ripristina le modifiche a package.json ed esegui di nuovo pnpm install.

Contributi

Signal accetta contributi esterni a questo progetto. Tuttavia, a meno che la modifica non sia semplice e facilmente comprensibile, ad esempio correggere un bug o un problema di portabilità, aggiungere un nuovo test, o migliorare le prestazioni, apri prima una issue per discutere la modifica che intendi apportare, poiché non tutte le modifiche possono essere accettate.

I contributi che non saranno usati direttamente da una delle app client ufficiali di Signal possono comunque essere presi in considerazione, ma solo se non rappresentano un onere di manutenzione eccessivo o non sono in conflitto con gli obiettivi del progetto.

La firma di un CLA (Contributor License Agreement) è richiesta per tutti i contributi.

Formattazione del codice e ringraziamenti

Puoi eseguire lo styler sull'intero progetto eseguendo:

just format-all

Puoi eseguire test più estesi, nonché linter e clippy, eseguendo:

just check-pre-commit

Quando fai una PR che modifica le dipendenze, dovrai rigenerare i nostri file di ringraziamenti. Vedi acknowledgments/README.md.

Questioni legali

Avviso sulla crittografia

Questa distribuzione include software crittografico. Il paese in cui risiedi attualmente potrebbe avere restrizioni sull'importazione, il possesso, l'uso e/o la riesportazione verso un altro paese di software di crittografia. PRIMA di usare qualsiasi software di crittografia, controlla le leggi, i regolamenti e le politiche del tuo paese riguardanti l'importazione, il possesso o l'uso, e la riesportazione di software di crittografia, per verificare se ciò è consentito. Vedi http://www.wassenaar.org/ per maggiori informazioni.

Il Dipartimento del Commercio del Governo degli Stati Uniti, Bureau of Industry and Security (BIS), ha classificato questo software come Export Commodity Control Number (ECCN) 5D002.C.1, che include software di sicurezza informatica che utilizza o esegue funzioni crittografiche con algoritmi asimmetrici. La forma e le modalità di questa distribuzione lo rendono idoneo per l'esportazione ai sensi dell'eccezione License Exception ENC Technology Software Unrestricted (TSU) (vedi il BIS Export Administration Regulations, Sezione 740.13) sia per il codice oggetto che per il codice sorgente.

Licenza

Copyright 2020-2026 Signal Messenger, LLC

Concesso in licenza sotto GNU AGPLv3: https://www.gnu.org/licenses/agpl-3.0.html