Visão Geral

libsignal contém APIs agnósticas de plataforma usadas pelos clientes e servidores oficiais do Signal, expostas como uma biblioteca Java, Swift ou TypeScript. As implementações subjacentes são escritas em Rust:

• libsignal-protocol: Implementa o protocolo Signal, incluindo o [algoritmo Double Ratchet][]. Um substituto para libsignal-protocol-java e libsignal-metadata-java.
• signal-crypto: Primitivas criptográficas como AES-GCM. Usamos as do RustCrypto sempre que possível, mas às vezes temos necessidades diferentes.
• device-transfer: Lógica de suporte para o recurso de transferência dispositivo-a-dispositivo do Signal.
• attest: Funcionalidade para atestação remota de [enclaves SGX][] e HSMs do lado do servidor.
• zkgroup: Funcionalidade para [grupos de conhecimento zero][] e recursos relacionados disponíveis no Signal.
• zkcredential: Uma abstração para o tipo de credenciais de conhecimento zero usadas pelo zkgroup, baseada no artigo "The Signal Private Group System" de Chase, Perrin e Zaverucha.
• poksho: Utilitários para implementar provas de conhecimento zero (como as usadas pelo zkgroup); significa "proof-of-knowledge, stateful-hash-object".
• account-keys: Funcionalidade para usar consistentemente PINs como senhas no sistema Secure Value Recovery do Signal, bem como outras operações de chave em toda a conta.
• usernames: Funcionalidade para geração, hashing e provas de nomes de usuário.
• media: Utilitários para manipulação de mídia.

Este repositório é usado pelos aplicativos cliente do Signal (Android, iOS e Desktop) bem como do lado do servidor. O uso fora do Signal não é suportado. Em particular, os produtos deste repositório são as bibliotecas Java, Swift e TypeScript que envolvem as implementações Rust subjacentes. Todas as APIs e implementações estão sujeitas a alterações sem aviso prévio, assim como as camadas de "ponte" JNI, C e add-on Node. No entanto, alterações incompatíveis com versões anteriores nas APIs Java, Swift, TypeScript e Rust não-ponte serão refletidas no número da versão na medida do possível, incluindo aumentos nas versões mínimas de ferramentas suportadas.

Compilação

Instalação do Toolchain

Para compilar qualquer coisa neste repositório, você deve ter o Rust instalado, bem como versões recentes do Clang, libclang, CMake, Make, protoc, Python (3.9+) e git.

Linux/Debian

Em um sistema similar ao Debian, você pode obter essas dependências extras através do apt:

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

macOS

No macOS, temos um script mantido com o melhor esforço possível para configurar o toolchain do Rust, que você pode executar com:

$ bin/mac_setup.sh

Rust

Primeira Compilação e Teste

A compilação atualmente usa uma versão específica do compilador Rust stable, que será baixada automaticamente pelo cargo. Para compilar e testar as bibliotecas básicas de protocolo:

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

Ferramentas Rust Adicionais

As ferramentas básicas acima devem ser suficientes para a maioria do desenvolvimento em Rust com libsignal.

Eventualmente, você pode descobrir que precisa de algumas ferramentas Rust adicionais, como taplo para formatação de código.

Você deve sempre instalar quaisquer ferramentas Rust necessárias que possam afetar a compilação através do cargo, em vez de usar o gerenciador de pacotes do seu sistema (por exemplo, apt ou brew). Os gerenciadores de pacotes às vezes contêm versões desatualizadas dessas ferramentas que podem quebrar a compilação com problemas de incompatibilidade.

Para instalar as principais dependências extras do Rust correspondentes às versões que usamos, você pode executar os seguintes comandos:

$ 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

Configuração / Configuração do Toolchain

Para compilar para Android, você deve instalar vários pacotes adicionais, incluindo um JDK, o Android NDK/SDK, e adicionar os alvos do Android ao compilador 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 você precisar de saídas 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"
  // A parte "uri()" só é necessária para Kotlin Gradle; Groovy Gradle aceita uma string simples aqui.
  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