概述

libsignal 包含官方 Signal 客户端和服务器所使用的平台无关 API，以 Java、Swift 或 TypeScript 库的形式提供。底层实现由 Rust 编写：

libsignal-protocol：实现 Signal 协议，包括 Double Ratchet algorithm。是 libsignal-protocol-java 和 libsignal-metadata-java 的替代品。
signal-crypto：AES-GCM 等密码学原语。我们尽可能使用 RustCrypto，但有时会有不同的需求。
device-transfer：为 Signal 的设备到设备传输功能提供支持逻辑。
attest：提供 SGX enclaves 远程证明和服务器端 HSMs 的功能。
zkgroup：提供 zero-knowledge groups 及 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 nightly 编译器，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，并使用以下命令将 Android 目标添加到 Rust 编译器中：

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 上，操作方法因发行版而异。对于基于 Debian 的发行版（如 Ubuntu），你可以使用：

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 的调试级和详细级日志；传递 -P jniTypeTagging 可在 Rust JNI 桥接代码中启用额外检查。

另外，也可以使用基于 Docker 的构建系统：

$ cd java
$ make

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

作为库使用

Signal 以 org.signal:libsignal-server、org.signal:libsignal-client 和 org.signal:libsignal-android 的名称发布供其自身使用的 Java 包。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 会在不过滤调试级和详细级日志的情况下重建。

当向 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 条），适用于目标代码和源代码。

许可证

Licensed under the GNU AGPLv3: https://www.gnu.org/licenses/agpl-3.0.html

libsignal

最受欢迎

概述

构建