Vue d'ensemble

libsignal contient des API indépendantes de la plateforme utilisées par les clients et serveurs officiels de Signal, exposées sous forme de bibliothèque Java, Swift ou TypeScript. Les implémentations sous-jacentes sont écrites en Rust :

• libsignal-protocol : implémente le protocole Signal, y compris l'[algorithme Double Ratchet][]. Un remplacement pour libsignal-protocol-java et libsignal-metadata-java.
• signal-crypto : primitives cryptographiques telles que AES-GCM. Nous utilisons celles de RustCrypto lorsque c'est possible, mais avons parfois des besoins différents.
• device-transfer : logique de prise en charge de la fonctionnalité de transfert de périphérique à périphérique de Signal.
• attest : fonctionnalité d'attestation à distance des [enclaves SGX][] et des [HSM][] côté serveur.
• zkgroup : fonctionnalité pour les [groupes à connaissance nulle][] et les fonctionnalités associées disponibles dans Signal.
• zkcredential : une abstraction pour le type d'informations d'identification à connaissance nulle utilisées par zkgroup, basée sur l'article « The Signal Private Group System » de Chase, Perrin et Zaverucha.
• poksho : utilitaires pour implémenter des preuves à connaissance nulle (telles que celles utilisées par zkgroup) ; signifie « proof-of-knowledge, stateful-hash-object ».
• account-keys : fonctionnalité pour utiliser de manière cohérente les [PIN][] comme mots de passe dans le système Secure Value Recovery de Signal, ainsi que d'autres opérations de clés à l'échelle du compte.
• usernames : fonctionnalité de génération, de hachage et de preuves de noms d'utilisateur.
• media : utilitaires de manipulation de médias.

Ce dépôt est utilisé par les applications clientes Signal (Android, iOS et Desktop) ainsi que côté serveur. L'utilisation en dehors de Signal n'est pas prise en charge. En particulier, les produits de ce dépôt sont les bibliothèques Java, Swift et TypeScript qui encapsulent les implémentations Rust sous-jacentes. Toutes les API et implémentations sont susceptibles d'être modifiées sans préavis, tout comme les couches « pont » JNI, C et module complémentaire Node. Cependant, les changements rétro-incompatibles des API Java, Swift, TypeScript et Rust hors pont seront reflétés dans le numéro de version au mieux, y compris les augmentations des versions minimales d'outils prises en charge.

Compilation

Installation de la chaîne d'outils

Pour compiler quoi que ce soit dans ce dépôt, vous devez avoir Rust installé, ainsi que des versions récentes de Clang, libclang, CMake, Make, protoc, Python (3.9+) et git.

Linux/Debian

Sur un système de type Debian, vous pouvez obtenir ces dépendances supplémentaires via apt :

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

macOS

Sur macOS, nous maintenons au mieux un script pour configurer la chaîne d'outils Rust que vous pouvez exécuter avec :

$ bin/mac_setup.sh

Rust

Première compilation et premiers tests

La compilation utilise actuellement une version spécifique du compilateur Rust stable, qui sera téléchargée automatiquement par cargo. Pour compiler et tester les bibliothèques de protocole de base :

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

Outils Rust supplémentaires

Les outils de base ci-dessus devraient vous permettre de démarrer la plupart des développements Rust de libsignal.

À terme, vous pourriez constater que vous avez besoin d'outils Rust supplémentaires comme taplo pour le formatage du code.

Vous devez toujours installer les outils Rust dont vous avez besoin et qui peuvent affecter la compilation depuis cargo plutôt que depuis votre gestionnaire de paquets système (par exemple apt ou brew). Les gestionnaires de paquets contiennent parfois des versions obsolètes de ces outils qui peuvent casser la compilation avec des problèmes d'incompatibilité (en particulier cbindgen).

Pour installer les principales dépendances Rust supplémentaires correspondant aux versions que nous utilisons, vous pouvez exécuter les commandes suivantes :

$ 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

Configuration de la chaîne d'outils

Pour compiler pour Android, vous devez installer plusieurs paquets supplémentaires, notamment un JDK, le NDK/SDK Android, et ajouter les cibles Android au compilateur Rust, en utilisant

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

Notre version de JDK officiellement prise en charge pour les compilations Android est JDK 21, donc assurez-vous d'installer par exemple OpenJDK 21, puis de pointer JAVA_HOME vers celui-ci.

Vous pouvez facilement le faire sur macOS via :

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

Sur Linux, la méthode varie selon la distribution. Pour les distributions basées sur Debian comme Ubuntu, vous pouvez utiliser :

sudo update-alternatives --config java

Nous versionnons également un fichier .tools_version à utiliser avec les gestionnaires de versions à l'exécution.

Compilation et tests

Pour compiler le jar et le aar Java/Android, et exécuter les tests :

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

Vous pouvez passer -P debugLevelLogs à Gradle pour compiler sans filtrer les journaux de niveau debug et verbose provenant de Rust, et -P jniTypeTagging pour activer des vérifications supplémentaires dans le code de pont JNI Rust.

Alternativement, un système de compilation utilisant Docker est disponible :

$ cd java
$ make

Lors de l'exposition de nouvelles API à Java, vous devrez exécuter rust/bridge/jni/bin/gen_java_decl.py en plus de recompiler. Cela nécessite l'installation de l'outil Rust cbindgen, comme détaillé ci-dessus.

Utilisation comme bibliothèque

Signal publie des paquets Java pour son propre usage, sous les noms org.signal:libsignal-server, org.signal:libsignal-client et org.signal:libsignal-android. libsignal-client et libsignal-server contiennent des bibliothèques natives pour Linux x86_64 de type Debian ainsi que Windows (x86_64) et macOS (x86_64 et arm64). libsignal-android contient des bibliothèques natives pour armeabi-v7a, arm64-v8a, x86 et x86_64 Android. Celles-ci se trouvent dans un dépôt Maven à l'adresse https://build-artifacts.signal.org/libraries/maven/ ; pour une utilisation depuis Gradle, ajoutez ce qui suit à votre bloc 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/")
}

Les anciennes compilations étaient publiées sur Maven Central à la place.