signalapp/libsignal
GitHub: signalapp/libsignal
Stars: 5533 | Forks: 685
# 概述
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 插件“bridge”层也是如此。但是，Java、Swift、TypeScript 和非 bridge Rust API 的向后不兼容更改将在版本号中反映出来（尽最大努力），包括增加最低支持工具版本。
# 构建
### 工具链安装
要构建本仓库中的任何内容，您必须安装 [Rust](https://rust-lang.org)，以及最新版本的 Clang、libclang、[CMake](https://cmake.org)、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 工具，例如 `cbindgen` 来修改到客户端库的 bridge，或者 `taplo` 用于代码格式化。
您应该始终从 cargo 而不是从系统包管理器（例如 `apt` 或 `brew`）安装任何可能影响构建的 Rust 工具。包管理器有时包含这些工具的过时版本，这可能会因不兼容问题导致构建中断（尤其是 cbindgen）。
要安装与我们使用的版本相匹配的主要 Rust 额外依赖项，您可以运行以下命令：
```
$ cargo +stable install --version "$(cat .cbindgen-version)" --locked cbindgen
$ 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 17，因此请确保安装例如 OpenJDK 17，然后将 JAVA_HOME 指向它。
您可以在 macOS 上通过以下方式轻松完成此操作：
```
export JAVA_HOME=$(/usr/libexec/java_home -v 17)
```
在 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
```
您可以将 `-P debugLevelLogs` 传递给 Gradle，以在不从 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](https://central.sonatype.org)。
为 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``](swift/)
## 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 时，除了重新构建外，您还需要运行 `rust/bridge/node/bin/gen_ts_decl.py`。
### 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 确实接受对本项目的外部贡献。但是，除非更改简单且易于理解，例如修复错误或可移植性问题、添加新测试或提高性能，否则请先打开一个 issue 讨论您的预期更改，因为并非所有更改都能被接受。
Signal 官方客户端应用程序之一不会直接使用的贡献可能仍会被考虑，但前提是它们不会造成过度的维护负担或与项目目标冲突。
所有贡献都需要签署 [CLA (Contributor License Agreement)](https://signal.org/cla/)。
## 代码格式化和致谢
您可以通过运行以下命令在整个项目上运行样式工具：
```
just format-all
```
您可以通过运行以下命令运行更广泛的测试以及 linter 和 clippy：
```
just check-pre-commit
```
当提交调整依赖项的 PR 时，您需要重新生成我们的致谢文件。请参阅 [``acknowledgments/README.md``](acknowledgments/)。
# 法律事项
## 加密通知
此分发包含加密软件。您当前居住的国家/地区可能对加密软件的进口、持有、使用和/或再出口到另一个国家/地区有限制。在使用任何加密软件之前，请检查您所在国家/地区关于加密软件的进口、持有或使用以及再出口的法律、法规和政策，以查看是否允许这样做。有关更多信息，请参阅
标签：AES-GCM, Bash脚本, CVE防护, Docker‑Compose, FFI, GUI应用, HSM, iOS, JS文件枚举, MITM代理, NoSQL注入, pip安装, Rust, Rust语言, SGX远程认证, Signal协议, Swift, TypeScript, Web界面, ZKGroup, 二进制文件分析, 加密原语, 即时通讯, 双棘轮算法, 可视化界面, 可视化调试, 安全备份, 安全插件, 安全通信, 安卓, 客户端库, 密码学, 带宽管理, 手动系统调用, 桌面应用, 流量可视化, 用户界面自定义, 目录枚举, 移动安全, 端到端加密, 网络安全, 网络流量审计, 跨平台UI框架, 通知系统, 通知系统, 隐私保护, 隐私计算, 零知识证明, 项目发现工具