업데이트로 돌아가기
New releaseSep 12, 2026

libsignal v0.102.2

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 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 시스템에서 PIN을 비밀번호로 일관되게 사용하기 위한 기능 및 기타 계정 전체 키 작업을 위한 기능입니다.
  • 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에서 설치해야 합니다. 패키지 관리자는 때때로 빌드를 호환성 문제로 중단시킬 수 있는 오래된 버전의 도구(특히 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의 디버그 및 상세 수준 로그를 필터링하지 않고 빌드할 수 있으며, -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용 네이티브 라이브러리를 포함합니다. 이들은 https://build-artifacts.signal.org/libraries/maven/ 의 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을 사용하며, Rust 라이브러리 빌드를 제어하는 Python 스크립트를 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은 Windows, macOS 및 Debian 계열 Linux용 네이티브 라이브러리를 포함하여 자체 사용을 위해 NPM 패키지 @signalapp/libsignal-client를 게시합니다. 세 플랫폼 모두에 대해 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은 이 프로젝트에 대한 외부 기여를 수용합니다. 그러나 변경 사항이 간단하고 쉽게 이해되는 경우(예: 버그 또는 이식성 문제 수정, 새 테스트 추가 또는 성능 개선)가 아니라면, 모든 변경 사항이 수용될 수 있는 것은 아니므로 먼저 이슈를 열어 의도한 변경 사항을 논의하세요.

Signal의 공식 클라이언트 앱 중 하나에서 직접 사용되지 않는 기여도 고려될 수 있지만, 과도한 유지 관리 부담을 초래하거나 프로젝트의 목표와 충돌하지 않는 경우에만 해당됩니다.

모든 기여에는 CLA(기여자 라이선스 계약) 서명이 필요합니다.

코드 포맷팅 및 감사의 글

다음을 실행하여 전체 프로젝트에 스타일러를 실행할 수 있습니다:

just format-all

다음을 실행하여 더 광범위한 테스트와 린터 및 clippy를 실행할 수 있습니다:

just check-pre-commit

종속성을 조정하는 PR을 만들 때는 감사의 글 파일을 재생성해야 합니다. acknowledgments/README.md를 참조하세요.

법적 사항

암호화 고지

이 배포판에는 암호화 소프트웨어가 포함되어 있습니다. 현재 거주하는 국가에서는 암호화 소프트웨어의 수입, 소유, 사용 및/또는 다른 국가로의 재수출에 제한이 있을 수 있습니다. 암호화 소프트웨어를 사용하기 전에, 수입, 소유 또는 사용, 그리고 암호화 소프트웨어의 재수출에 관한 해당 국가의 법률, 규정 및 정책을 확인하여 이것이 허용되는지 확인하세요. 자세한 내용은 http://www.wassenaar.org/를 참조하세요.

미국 정부 상무부 산업안보국(BIS)은 이 소프트웨어를 비대칭 알고리즘을 사용하거나 암호화 기능을 수행하는 정보 보안 소프트웨어를 포함하는 수출 통제 분류 번호(ECCN) 5D002.C.1로 분류했습니다. 이 배포의 형식과 방식은 객체 코드와 소스 코드 모두에 대해 라이선스 예외 ENC 기술 소프트웨어 무제한(TSU) 예외(BIS 수출 관리 규정 섹션 740.13 참조)에 따라 수출 자격이 있습니다.

라이선스

Copyright 2020-2026 Signal Messenger, LLC

GNU AGPLv3에 따라 라이선스가 부여됩니다: https://www.gnu.org/licenses/agpl-3.0.html

더 읽기

카테고리

Encryption/Decryption ToolsIdentity ManagementCryptographyPrivacyHardware Security