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 quando 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 subjacentes em Rust. 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 do 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 na medida do 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 estável do Rust, que será baixada automaticamente pelo cargo. Para compilar e testar as bibliotecas básicas do protocolo:

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

Ferramentas Rust Adicionais

As ferramentas básicas acima devem ser suficientes para a maioria do desenvolvimento em Rust do 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 que possam afetar a compilação a partir 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 (especialmente o cbindgen).

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 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

Nossa versão de JDK oficialmente suportada para compilações Android é o JDK 21, então certifique-se de instalar, por exemplo, o OpenJDK 21, e então apontar JAVA_HOME para ele.

Você pode fazer isso facilmente no macOS via:

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

No Linux, a forma de fazer isso varia por distribuição. Para distribuições baseadas em Debian como o Ubuntu, você pode usar:

sudo update-alternatives --config java

Também mantemos um arquivo .tools_version para uso com gerenciadores de versão em tempo de execução.

Compilação e Teste

Para compilar o jar e o aar Java/Android, e executar os testes:

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

Você pode passar -P debugLevelLogs para o Gradle para compilar sem filtrar os logs de nível debug e verbose do Rust, e -P jniTypeTagging para habilitar verificações adicionais no código de ponte JNI do Rust.

Alternativamente, um sistema de compilação usando Docker está disponível:

$ cd java
$ make

Ao expor novas APIs para Java, você precisará executar rust/bridge/jni/bin/gen_java_decl.py além de recompilar. Isso requer a instalação da ferramenta Rust cbindgen, conforme detalhado acima.

Uso como biblioteca

O Signal publica pacotes Java para seu próprio uso, sob os nomes org.signal:libsignal-server, org.signal:libsignal-client e org.signal:libsignal-android. libsignal-client e libsignal-server contêm bibliotecas nativas para Linux x86_64 com sabor Debian, bem como Windows (x86_64) e macOS (x86_64 e arm64). libsignal-android contém bibliotecas nativas para armeabi-v7a, arm64-v8a, x86 e x86_64 Android. Estas estão localizadas em um repositório Maven em https://build-artifacts.signal.org/libraries/maven/; para uso a partir do Gradle, adicione o seguinte ao seu bloco 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/")
}

Compilações mais antigas eram publicadas no Maven Central.

Ao compilar para Android você precisa de ambas libsignal-android e libsignal-client, mas as bibliotecas Windows e macOS em libsignal-client não serão automaticamente excluídas do seu aplicativo final. Você pode excluí-las explicitamente usando packaging:

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