Обзор

libsignal содержит платформенно-независимые API, используемые официальными клиентами и серверами Signal, предоставляемые в виде библиотеки для Java, Swift или TypeScript. Базовые реализации написаны на Rust:

libsignal-protocol: Реализует протокол Signal, включая алгоритм Double Ratchet. Замена libsignal-protocol-java и libsignal-metadata-java.
signal-crypto: Криптографические примитивы, такие как AES-GCM. Мы используем RustCrypto, где это возможно, но иногда у нас есть отличающиеся потребности.
device-transfer: Логика поддержки функции передачи данных между устройствами Signal.
attest: Функциональность для удалённой аттестации анклавов SGX и серверных HSM.
zkgroup: Функциональность для групп с нулевым разглашением и связанных функций, доступных в Signal.
zkcredential: Абстракция для типа учётных данных с нулевым разглашением, используемых zkgroup, основанная на статье "The Signal Private Group System" авторов Chase, Perrin и Zaverucha.
poksho: Утилиты для реализации доказательств с нулевым разглашением (таких как используемые zkgroup); расшифровывается как "proof-of-knowledge, stateful-hash-object".
account-keys: Функциональность для последовательного использования PIN-кодов в качестве паролей в системе Secure Value Recovery от Signal, а также другие операции с ключами уровня аккаунта.
usernames: Функциональность для генерации имён пользователей, хеширования и доказательств.
media: Утилиты для работы с медиа.

Этот репозиторий используется клиентскими приложениями Signal (Android, iOS и Desktop), а также на стороне сервера. Использование вне Signal не поддерживается. В частности, продуктами этого репозитория являются библиотеки для Java, Swift и TypeScript, которые оборачивают базовые реализации на Rust. Все API и реализации могут быть изменены без предварительного уведомления, как и "мостовые" слои JNI, C и Node add-on. Однако обратно несовместимые изменения в API для Java, Swift, TypeScript и не-мостовых Rust API будут по мере возможности отражаться в номере версии, включая повышение минимальных поддерживаемых версий инструментов.

Сборка

Установка инструментария

Чтобы собрать что-либо в этом репозитории, у вас должен быть установлен Rust, а также свежие версии Clang, libclang, CMake, Make, protoc, Python (3.9+) и git.

Linux/Debian

В Debian-подобной системе вы можете получить эти дополнительные зависимости через apt:

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

macOS

В macOS у нас есть поддерживаемый по мере возможности скрипт для настройки инструментария Rust, который можно запустить так:

$ bin/mac_setup.sh

Rust

Первая сборка и тестирование

Сборка в настоящее время использует определённую версию стабильного компилятора Rust, которая будет автоматически загружена cargo. Чтобы собрать и протестировать базовые протокольные библиотеки:

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

Дополнительные инструменты Rust

Базовых инструментов выше должно быть достаточно для большинства задач разработки на Rust в libsignal.

Со временем вы можете обнаружить, что вам нужны дополнительные инструменты Rust, такие как taplo для форматирования кода.

Вам всегда следует устанавливать любые необходимые инструменты Rust, которые могут повлиять на сборку, из cargo, а не из системного менеджера пакетов (например, apt или brew). Менеджеры пакетов иногда содержат устаревшие версии этих инструментов, которые могут сломать сборку из-за проблем с совместимостью (особенно cbindgen).

Чтобы установить основные дополнительные зависимости Rust, соответствующие используемым нами версиям, можно выполнить следующие команды:

$ 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

Настройка/конфигурация инструментария

Чтобы собрать для Android, вы должны установить несколько дополнительных пакетов, включая JDK, Android NDK/SDK, и добавить цели Android в компилятор Rust, используя

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

Наша официально поддерживаемая версия JDK для сборок Android — JDK 21, поэтому обязательно установите, например, OpenJDK 21, а затем укажите JAVA_HOME на него.

Вы легко можете сделать это в macOS через:

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

В Linux способ зависит от дистрибутива. Для Debian-подобных дистрибутивов, таких как Ubuntu, можно использовать:

sudo update-alternatives --config java

Мы также добавляем в репозиторий файл .tools_version для использования с менеджерами версий времени выполнения.

Сборка и тестирование

Чтобы собрать Java/Android jar и aar, а также запустить тесты:

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

Вы можете передать -P debugLevelLogs в Gradle, чтобы собрать без фильтрации отладочных и подробных логов из Rust, и -P jniTypeTagging, чтобы включить дополнительные проверки в коде моста Rust JNI.

В качестве альтернативы доступна система сборки с использованием Docker:

$ cd java
$ make

При предоставлении новых API для Java вам нужно будет запустить rust/bridge/jni/bin/gen_java_decl.py в дополнение к пересборке. Для этого требуется установить инструмент Rust cbindgen, как описано выше.

Использование в качестве библиотеки

Signal публикует Java-пакеты для собственного использования под именами org.signal:libsignal-server, org.signal:libsignal-client и org.signal:libsignal-android. libsignal-client и libsignal-server содержат нативные библиотеки для Debian-подобного x86_64 Linux, а также Windows (x86_64) и macOS (x86_64 и arm64). libsignal-android содержит нативные библиотеки для armeabi-v7a, arm64-v8a, x86 и x86_64 Android. Они расположены в Maven-репозитории по адресу https://build-artifacts.signal.org/libraries/maven/; для использования из Gradle добавьте следующее в ваш блок 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/")
}

Более старые сборки публиковались в Maven Central.

При сборке для Android вам нужны обе библиотеки: libsignal-android и libsignal-client, но библиотеки для Windows и macOS из libsignal-client не будут автоматически исключены из вашего финального приложения. Вы можете явно исключить их, используя packaging:

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

Дополнительно вы можете исключить libsignal_jni_testing.so, если не планируете использовать какие-либо API, предназначенные для клиентского тестирования.

libsignal

Популярное