개요

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 enclaves와 서버 측 HSMs의 원격 증명을 위한 기능입니다.
• 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 시스템에서 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 개발 환경을 설정하는 데 충분합니다.

결국 코드 포맷팅을 위한 taplo와 같은 추가 Rust 도구가 필요할 수 있습니다.

빌드에 영향을 줄 수 있는 필요한 Rust 도구는 항상 시스템 패키지 관리자(예: apt 또는 brew)가 아닌 cargo를 통해 설치해야 합니다. 패키지 관리자는 때때로 호환성 문제로 빌드를 중단시킬 수 있는 오래된 버전의 도구를 포함하고 있을 수 있습니다.

우리가 사용하는 버전과 일치하는 주요 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

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:

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:

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:

$ 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:

$ 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 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

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 npm as our package manager, and a Python script to control building the Rust library, accessible as npm run build.

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

When testing changes locally, you can use npm run build to do an incremental rebuild of the Rust library. Alternately, npm 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.

NPM