Обзор

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, предназначенные для клиентского тестирования.

Тестирование локальной сборки с Signal-Android

В файле gradle.properties проекта Signal-Android есть закомментированная строка для включения libsignal в сборку. Раскомментируйте её и скорректируйте путь; при желании вы можете ограничить архитектуры, для которых хотите собирать, добавив androidArchs=aarch64 в gradle.properties libsignal. (Набор распознаваемых архитектур находится в java/build_jni.sh.) Если вы используете IDE, вам нужно будет повторно импортировать структуру Gradle на этом этапе. Когда закончите, откатите изменения в gradle.properties приложения Android и импортируйте ещё раз.

Обратите внимание, что это не импортирует Rust-части проекта в IDE. Сделать это в мультиязычной IDE вроде IDEA возможно, но капризно; по состоянию на 2025 год самый надёжный способ — сначала открыть проект Android, затем добавить корневую директорию репозитория libsignal как проект Rust (включив только директорию верхнего уровня), и только после этого вносить изменения в gradle.properties.

Swift

Чтобы узнать о процессе сборки Swift, см. swift/README.md

Node

Для сборки вам понадобится установленный Node. Если у вас есть nvm, вы можете запустить nvm use, чтобы автоматически выбрать подходящую версию.

Мы используем npm в качестве менеджера пакетов и Python-скрипт для управления сборкой библиотеки Rust, доступный как npm run build.

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

При локальном тестировании изменений вы можете использовать npm run build для инкрементальной пересборки библиотеки Rust. В качестве альтернативы npm run build-with-debug-level-logs пересоберёт без фильтрации отладочных и подробных логов.

При предоставлении новых API для Node вам нужно будет запустить just generate-node в дополнение к пересборке.

NPM

Signal публикует NPM-пакет @signalapp/libsignal-client для собственного использования, включая нативные библиотеки для Windows, macOS и Debian-подобного Linux. Для всех трёх платформ включены сборки как x64, так и arm64, но сборки arm64 для Windows и Linux считаются экспериментальными, поскольку официальных сборок Signal для этих архитектур нет.

Тестирование локальной сборки с Signal-Desktop

После выполнения всех команд сборки выше измените зависимость @signalapp/libsignal-client в package.json приложения Desktop на "link:path/to/libsignal/node" и запустите pnpm install. Когда закончите, откатите изменения в package.json и снова запустите pnpm install.

Вклад

Signal принимает внешний вклад в этот проект. Однако, если изменение не простое и легко понятное, например исправление ошибки или проблемы с переносимостью, добавление нового теста или улучшение производительности, сначала откройте issue, чтобы обсудить предполагаемое изменение, так как не все изменения могут быть приняты.

Вклад, который не будет использоваться напрямую одним из официальных клиентских приложений Signal, всё ещё может быть рассмотрен, но только если он не создаёт чрезмерного бремени по сопровождению и не противоречит целям проекта.

Подписание CLA (Contributor License Agreement) требуется для любого вклада.

Форматирование кода и благодарности

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

just format-all

Вы можете запустить более обширные тесты, а также линтеры и clippy, выполнив:

just check-pre-commit

При создании PR, который изменяет зависимости, вам нужно будет перегенерировать наши файлы благодарностей. См. acknowledgments/README.md.

Юридические аспекты

Уведомление о криптографии

Этот дистрибутив включает криптографическое программное обеспечение. Страна, в которой вы в настоящее время проживаете, может иметь ограничения на импорт, владение, использование и/или реэкспорт в другую страну программного обеспечения для шифрования. ПЕРЕД использованием любого программного обеспечения для шифрования, пожалуйста, проверьте законы, нормативные акты и политику вашей страны относительно импорта, владения или использования и реэкспорта программного обеспечения для шифрования, чтобы узнать, разрешено ли это. См. http://www.wassenaar.org/ для получения дополнительной информации.

Министерство торговли США, Бюро промышленности и безопасности (BIS), классифицировало это программное обеспечение как Export Commodity Control Number (ECCN) 5D002.C.1, который включает программное обеспечение для информационной безопасности, использующее или выполняющее криптографические функции с асимметричными алгоритмами. Форма и способ этого распространения делают его подходящим для экспорта в рамках исключения License Exception ENC Technology Software Unrestricted (TSU) (см. BIS Export Administration Regulations, Section 740.13) как для объектного кода, так и для исходного кода.

Лицензия

Copyright 2020-2026 Signal Messenger, LLC

Лицензировано под GNU AGPLv3: https://www.gnu.org/licenses/agpl-3.0.html