概述

libsignal 包含官方 Signal 客户端和服务器所使用的平台无关 API，以 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 enclaves 和服务器端 HSMs 远程证明的功能。
zkgroup：Signal 中可用的[零知识群组][]及相关功能。
zkcredential：对 zkgroup 所使用的那类零知识凭证的抽象，基于 Chase、Perrin 和 Zaverucha 的论文《The Signal Private Group System》。
poksho：用于实现零知识证明（例如 zkgroup 所使用的那些）的工具；代表 "proof-of-knowledge, stateful-hash-object"。
account-keys：在 Signal 的 Secure Value Recovery 系统中一致地将 PINs 用作密码的功能，以及其他账户级密钥操作。
usernames：用户名生成、哈希和证明的功能。
media：用于处理媒体的工具。

本仓库被 Signal 客户端应用（Android、iOS 和 Desktop）以及服务器端使用。不支持在 Signal 之外使用。特别是，本仓库的产物是封装底层 Rust 实现的 Java、Swift 和 TypeScript 库。所有 API 和实现均可能在不另行通知的情况下变更，JNI、C 和 Node 插件“桥接”层也是如此。但是，对 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 工具

上述基础工具应能满足大多数 libsignal Rust 开发的需要。

最终你可能会发现需要一些额外的 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，并向 Rust 编译器添加 Android 目标，使用

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

我们官方支持的 Android 构建 JDK 版本是 JDK 21，因此请务必安装例如 OpenJDK 21，然后将 JAVA_HOME 指向它。

在 macOS 上，你可以通过以下方式轻松完成：

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

在 Linux 上，具体做法因发行版而异。对于 Ubuntu 等基于 Debian 的发行版，你可以使用：

sudo update-alternatives --config java

我们还检入了一个 .tools_version 文件，供运行时版本管理器使用。

构建与测试

要构建 Java/Android 的 jar 和 aar，并运行测试：

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

你可以向 Gradle 传递 -P debugLevelLogs，以在构建时不过滤来自 Rust 的 debug 和 verbose 级别日志；传递 -P jniTypeTagging 以在 Rust JNI 桥接代码中启用额外检查。

或者，也可以使用基于 Docker 的构建系统：

$ cd java
$ make

在向 Java 暴露新 API 时，除了重新构建之外，你还需要运行 rust/bridge/jni/bin/gen_java_decl.py。这需要安装 cbindgen Rust 工具，详见上文。

作为库使用

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，但 libsignal-client 中的 Windows 和 macOS 库不会自动从你的最终应用中排除。你可以使用 packaging 显式排除它们：

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

如果你不打算使用任何面向客户端测试的 API，还可以额外排除 libsignal_jni_testing.so。

使用 Signal-Android 测试本地构建

Signal-Android 的 gradle.properties 文件中有一行被注释掉的配置，用于将 libsignal 纳入构建。取消注释并调整路径；可选地，你可以通过在 libsignal 的 gradle.properties 中添加 androidArchs=aarch64 来限制要构建的架构。（可识别的架构集合位于 java/build_jni.sh 中。）如果你使用 IDE，此时需要重新导入 Gradle 结构。完成后，请还原对 Android 应用 gradle.properties 的更改并再次重新导入。

请注意，这不会将项目的 Rust 部分导入 IDE。在像 IDEA 这样的多语言 IDE 中这样做是可行的，但很麻烦；截至 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 将在重建时不过滤 debug 和 verbose 级别日志。

在向 Node 暴露新 API 时，除了重新构建之外，你还需要运行 just generate-node。

NPM

Signal 发布供自己使用的 NPM 包 @signalapp/libsignal-client，包含适用于 Windows、macOS 和 Debian 系 Linux 的原生库。三个平台都包含 x64 和 arm64 构建，但 Windows 和 Linux 的 arm64 构建被视为实验性的，因为 Signal 没有针对这些架构的官方构建。

使用 Signal-Desktop 测试本地构建

运行完上述所有构建命令后，将 Desktop 应用 package.json 中的 @signalapp/libsignal-client 依赖调整为 "link:path/to/libsignal/node" 并运行 pnpm install。完成后，请还原对 package.json 的更改并再次运行 pnpm install。

贡献

Signal 确实接受对本项目的外部贡献。但是，除非更改简单且易于理解，例如修复 bug 或可移植性问题、添加新测试或改进性能，否则请先开一个 issue 讨论你打算进行的更改，因为并非所有更改都能被接受。

不会被 Signal 官方客户端应用直接使用的贡献仍可能被考虑，但前提是它们不会造成不适当的维护负担或与项目目标冲突。

所有贡献都需要签署 CLA（贡献者许可协议）。

代码格式化与致谢

你可以通过运行以下命令在整个项目上运行格式化工具：

just format-all

你可以通过运行以下命令来运行更广泛的测试以及 linter 和 clippy：

just check-pre-commit

在提交调整依赖的 PR 时，你需要重新生成我们的致谢文件。请参阅 acknowledgments/README.md。

法律事项

密码学声明

本发行版包含密码学软件。你当前居住的国家可能对加密软件的进口、持有、使用和/或再出口到另一个国家有限制。在使用任何加密软件之前，请检查你所在国家关于加密软件进口、持有或使用以及再出口的法律、法规和政策，以确认是否允许。更多信息请参见 http://www.wassenaar.org/。

美国商务部工业与安全局（BIS）已将本软件归类为出口商品管制编号（ECCN）5D002.C.1，其中包括使用或执行非对称算法密码学功能的信息安全软件。本发行版的形式和方式使其有资格根据许可例外 ENC 技术软件无限制（TSU）例外（参见 BIS 出口管理条例第 740.13 节）出口，适用于目标代码和源代码。

许可证

根据 GNU AGPLv3 许可：https://www.gnu.org/licenses/agpl-3.0.html

libsignal v0.102.2

分类