
Signal Protocol과 Signal을 가능하게 하는 기타 암호화 프리미티브의 본거지입니다.
# 개요
libsignal은 공식 Signal 클라이언트와 서버에서 사용되는 플랫폼 독립적인 API를 포함하며, Java, Swift 또는 TypeScript 라이브러리로 제공됩니다. 기반 구현은 Rust로 작성되었습니다:
- libsignal-protocol: [Double Ratchet 알고리즘][]을 포함한 Signal 프로토콜을 구현합니다. [libsignal-protocol-java][] 및 [libsignal-metadata-java][]의 대체 구현입니다.
- signal-crypto: AES-GCM과 같은 암호화 기본 요소입니다. 가능한 경우 [RustCrypto][]의 것을 사용하지만 때로는 다른 요구 사항이 있습니다.
- device-transfer: Signal의 기기 간 전송 기능을 위한 지원 로직입니다.
- attest: [SGX enclave][] 및 서버 측 [HSM][]의 원격 증명을 위한 기능입니다.
- zkgroup: Signal에서 사용 가능한 [영지식 그룹][] 및 관련 기능을 위한 기능입니다.
- zkcredential: Chase, Perrin, Zaverucha의 논문 "[The Signal Private Group System][]"을 기반으로 한, zkgroup에서 사용되는 영지식 자격 증명에 대한 추상화입니다.
- poksho: 영지식 증명(예: zkgroup에서 사용되는 것)을 구현하기 위한 유틸리티로, "proof-of-knowledge, stateful-hash-object"의 약자입니다.
- account-keys: Signal의 Secure Value Recovery 시스템에서 [PIN][]을 비밀번호로 일관되게 사용하기 위한 기능 및 기타 계정 전체 키 작업을 위한 기능입니다.
- usernames: 사용자 이름 생성, 해싱 및 증명을 위한 기능입니다.
- media: 미디어 조작을 위한 유틸리티입니다.
이 저장소는 Signal 클라이언트 앱([Android][], [iOS][], [Desktop][])과 서버 측에서 사용됩니다. Signal 외부에서의 사용은 지원되지 않습니다. 특히, 이 저장소의 산출물은 기반 Rust 구현을 감싸는 Java, Swift, TypeScript 라이브러리입니다. 모든 API와 구현은 예고 없이 변경될 수 있으며, JNI, C, Node 애드온 "브리지" 계층도 마찬가지입니다. 다만 Java, Swift, TypeScript 및 비브리지 Rust API에 대한 하위 호환되지 않는 변경 사항은 최선의 노력으로 버전 번호에 반영되며, 최소 지원 도구 버전의 상향도 포함됩니다.
[Double Ratchet 알고리즘]: https://signal.org/docs/
[libsignal-protocol-java]: https://github.com/signalapp/libsignal-protocol-java
[libsignal-metadata-java]: https://github.com/signalapp/libsignal-metadata-java
[RustCrypto]: https://github.com/RustCrypto
[Noise protocol]: http://noiseprotocol.org/
[SGX enclave]: https://www.intel.com/content/www/us/en/architecture-and-technology/software-guard-extensions.html
[HSM]: https://en.wikipedia.org/wiki/Hardware_security_module
[영지식 그룹]: https://signal.org/blog/signal-private-group-system/
[The Signal Private Group System]: https://eprint.iacr.org/2019/1416.pdf
[PIN]: https://signal.org/blog/signal-pins/
[Android]: https://github.com/signalapp/Signal-Android
[iOS]: https://github.com/signalapp/Signal-iOS
[Desktop]: https://github.com/signalapp/Signal-Desktop
# 빌드
### 툴체인 설치
이 저장소의 무엇이든 빌드하려면 [Rust](https://rust-lang.org)가 설치되어 있어야 하며, 최신 버전의 Clang, libclang, [CMake](https://cmake.org), Make, protoc, Python(3.11+), git도 필요합니다.
#### Linux/Debian
Debian 계열 시스템에서는 `apt`를 통해 이러한 추가 의존성을 설치할 수 있습니다:
```shell
$ apt-get install clang libclang-dev cmake make protobuf-compiler libprotobuf-dev python3 git
```
#### macOS
macOS에서는 Rust 툴체인을 설정하기 위해 최선을 다해 유지 관리되는 스크립트가 있으며, 다음을 실행하여 사용할 수 있습니다:
```shell
$ bin/mac_setup.sh
```
## Rust
### 첫 빌드 및 테스트
빌드는 현재 특정 버전의 Rust 안정 컴파일러를 사용하며,
이는 cargo에 의해 자동으로 다운로드됩니다. 기본 프로토콜
라이브러리를 빌드하고 테스트하려면:
```shell
$ cargo build
...
$ cargo test
...
```
### 추가 Rust 도구
위의 기본 도구들은 대부분의 libsignal Rust 개발 환경을 설정하는 데 충분합니다.
결국 코드 포맷팅을 위한 `taplo`와 같은 추가 Rust 도구가 필요할 수 있습니다.
빌드에 영향을 줄 수 있는 필요한 Rust 도구는 항상 시스템 패키지 관리자(예: `apt` 또는 `brew`)가 아닌 cargo를 통해 설치해야 합니다. 패키지 관리자는 때때로 호환성 문제로 빌드를 중단시킬 수 있는 오래된 버전의 도구를 포함하고 있을 수 있습니다.
우리가 사용하는 버전과 일치하는 주요 Rust 추가 의존성을 설치하려면 다음 명령을 실행할 수 있습니다:
```shell
$ 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```
Our officially supported JDK version for Android builds is JDK 21, so be sure to install e.g. OpenJDK 21, and then point JAVA_HOME to it.
You can easily do this on macOS via:
```shell
export JAVA_HOME=$(/usr/libexec/java_home -v 21)
```
On Linux, the way you do this varies by distribution. For Debian based distributions like Ubuntu, you can use:
```shell
sudo update-alternatives --config java
```
We also check-in a `.tools_version` file for use with runtime version managers.
### Building and Testing
To build the Java/Android ``jar`` and ``aar``, and run the tests:
```shell
$ cd java
$ ./gradlew test
$ ./gradlew build # AAR 출력이 필요한 경우
```
You can pass `-P debugLevelLogs` to Gradle to build without filtering out debug- and verbose-level
logs from Rust, and `-P jniTypeTagging` to enable additional checks in the Rust JNI bridging code.
Alternately, a build system using Docker is available:
```shell
$ cd java
$ make
```
When exposing new APIs to Java, you will need to run `cargo run -p libsignal-jni-native_kt` (or
`just generate-jni`) in addition to rebuilding.
### Use as a library
Signal publishes Java packages for its own use, under the names org.signal:libsignal-server,
org.signal:libsignal-client, and org.signal:libsignal-android. libsignal-client and libsignal-server
contain native libraries for Debian-flavored x86_64 Linux as well as Windows (x86_64) and macOS
(x86_64 and arm64). libsignal-android contains native libraries for armeabi-v7a, arm64-v8a, x86, and
x86_64 Android. These are located in a Maven repository at
https://build-artifacts.signal.org/libraries/maven/; for use from Gradle, add the following to your
`repositories` block:
```
maven {
name = "SignalBuildArtifacts"
// "uri()" 부분은 Kotlin Gradle에서만 필요합니다. Groovy Gradle은 여기서 일반 문자열을 허용합니다.
url = uri("https://build-artifacts.signal.org/libraries/maven/")
}
```
Older builds were published to [Maven Central](https://central.sonatype.org) instead.
When building for Android you need *both* libsignal-android and libsignal-client, but the Windows
and macOS libraries in libsignal-client won't automatically be excluded from your final app. You can
explicitly exclude them using `packaging`:
```
android {
// ...
packaging {
resources {
excludes += setOf("libsignal_jni*.dylib", "signal_jni*.dll")
}
}
// ...
}
```
You can additionally exclude `libsignal_jni_testing.so` if you do not plan to use any of the APIs
intended for client testing.
### Testing a local build with Signal-Android
The Signal-Android gradle.properties file has a commented-out line to include libsignal as part of the build. Uncomment that and adjust the path; optionally, you can restrict the architectures you want to build for by adding `androidArchs=aarch64` to *libsignal's* gradle.properties. (The set of recognized architectures is in java/build_jni.sh.) If you're using an IDE, you'll need to re-import the Gradle structure at this point. When you're done, revert the changes to the Android app's gradle.properties and re-import once more.
Note that this does not import the *Rust* parts of the project into the IDE. Doing that in a multi-language IDE like IDEA is possible, but finicky; as of 2025 the most reliable way to do it is to open the Android project first, add the libsignal repo root directory as a Rust project second (only including the top-level directory), and only then make the changes to gradle.properties.
## Swift
To learn about the Swift build process see [``swift/README.md``](https://github.com/signalapp/libsignal/blob/main/swift)
## Node
You'll need Node installed to build. If you have [nvm][], you can run `nvm use` to select an
appropriate version automatically.
We use `pnpm` as our package manager, and a Python script to control building the Rust library, accessible as `pnpm run build`.
```shell
$ cd node
$ nvm use
$ npm install -g pnpm # 또는 `npx pnpm` 사용
$ pnpm install
$ pnpm run build
$ pnpm run tsc
$ pnpm run test
```
When testing changes locally, you can use `pnpm run build` to do an incremental rebuild of the Rust library. Alternately, `pnpm run build-with-debug-level-logs` will rebuild without filtering out debug- and verbose-level logs.
When exposing new APIs to Node, you will need to run `just generate-node` in
addition to rebuilding.
[nvm]: https://github.com/nvm-sh/nvm
### NPM
Signal publishes the NPM package `@signalapp/libsignal-client` for its own use, including native
libraries for Windows, macOS, and Debian-flavored Linux. Both x64 and arm64 builds are included for
all three platforms, but the arm64 builds for Windows and Linux are considered experimental, since
there are no official builds of Signal for those architectures.
### Testing a local build with Signal-Desktop
After running all the build commands above, adjust the `@signalapp/libsignal-client` dependency in the Desktop app's package.json to "link:path/to/libsignal/node" and run `pnpm install`. When you're done, revert the changes to package.json and run `pnpm install` again.
# Contributions
Signal does accept external contributions to this project. However unless the change is
simple and easily understood, for example fixing a bug or portability issue, adding a new
test, or improving performance, first open an issue to discuss your intended change as not
all changes can be accepted.
Contributions that will not be used directly by one of Signal's official client apps may still be
considered, but only if they do not pose an undue maintenance burden or conflict with the goals of
the project.
Signing a [CLA (Contributor License Agreement)](https://signal.org/cla/) is required for all contributions.
## Code Formatting and Acknowledgments
You can run the styler on the entire project by running:
```shell
just format-all
```
You can run more extensive tests as well as linters and clippy by running:
```shell
just check-pre-commit
```
When making a PR that adjusts dependencies, you'll need to regenerate our acknowledgments files. See [``acknowledgments/README.md``](https://github.com/signalapp/libsignal/blob/main/acknowledgments).
# Legal things
## Cryptography Notice
This distribution includes cryptographic software. The country in which you currently reside may have restrictions on
the import, possession, use, and/or re-export to another country, of encryption software. BEFORE using any encryption
software, please check your country's laws, regulations and policies concerning the import, possession, or use, and
re-export of encryption software, to see if this is permitted. See <http://www.wassenaar.org/> for more information.
The U.S. Government Department of Commerce, Bureau of Industry and Security (BIS), has classified this software as
Export Commodity Control Number (ECCN) 5D002.C.1, which includes information security software using or performing
cryptographic functions with asymmetric algorithms. The form and manner of this distribution makes it eligible for
export under the License Exception ENC Technology Software Unrestricted (TSU) exception (see the BIS Export
Administration Regulations, Section 740.13) for both object code and source code.
## License
Copyright 2020-2026 Signal Messenger, LLC
Licensed under the GNU AGPLv3: https://www.gnu.org/licenses/agpl-3.0.html