
libsignal v0.102.2
موطن بروتوكول Signal وكذلك الأوليات التشفيرية الأخرى التي تجعل Signal ممكنًا.
نظرة عامة
يحتوي libsignal على واجهات برمجة تطبيقات (APIs) مستقلة عن المنصة تستخدمها عملاء وخوادم Signal الرسمية، ومتاحة كمكتبة Java أو Swift أو TypeScript. كُتبت التنفيذات الأساسية بلغة Rust:
- libsignal-protocol: ينفّذ بروتوكول Signal، بما في ذلك [خوارزمية Double Ratchet][]. بديل عن libsignal-protocol-java وlibsignal-metadata-java.
- signal-crypto: أوليات تشفيرية مثل AES-GCM. نستخدم أوليات RustCrypto حيثما أمكن لكن لدينا أحيانًا احتياجات مختلفة.
- device-transfer: منطق الدعم لميزة النقل من جهاز إلى جهاز في Signal.
- attest: وظائف الإثبات عن بُعد لـ SGX enclaves وHSMs من جهة الخادم.
- zkgroup: وظائف [المجموعات ذات المعرفة الصفرية][] والميزات ذات الصلة المتاحة في Signal.
- zkcredential: تجريد لنوع بيانات الاعتماد ذات المعرفة الصفرية المستخدمة في zkgroup، استنادًا إلى الورقة البحثية "The Signal Private Group System" لـ Chase وPerrin وZaverucha.
- poksho: أدوات مساعدة لتنفيذ إثباتات المعرفة الصفرية (مثل تلك المستخدمة في zkgroup)؛ وهو اختصار لـ "proof-of-knowledge, stateful-hash-object".
- account-keys: وظائف للاستخدام المتسق لـ PINs ككلمات مرور في نظام الاسترداد الآمن للقيم (Secure Value Recovery) في Signal، بالإضافة إلى عمليات المفاتيح الأخرى على مستوى الحساب.
- usernames: وظائف لتوليد أسماء المستخدمين وتجزئتها وإثباتاتها.
- media: أدوات مساعدة لمعالجة الوسائط.
يُستخدم هذا المستودع من قِبل تطبيقات عميل Signal (Android وiOS وDesktop) وكذلك من جهة الخادم. الاستخدام خارج Signal غير مدعوم. على وجه الخصوص، فإن منتجات هذا المستودع هي مكتبات Java وSwift وTypeScript التي تغلّف تنفيذات Rust الأساسية. جميع واجهات برمجة التطبيقات والتنفيذات عرضة للتغيير دون إشعار، وكذلك طبقات "الجسر" الخاصة بـ JNI وC وإضافة Node. ومع ذلك، فإن التغييرات غير المتوافقة مع الإصدارات السابقة على واجهات Java وSwift وTypeScript و واجهات Rust غير الجسرية ستُعكس في رقم الإصدار على أساس بذل أفضل جهد، بما في ذلك الزيادات في الحد الأدنى لإصدارات الأدوات المدعومة.
البناء
تثبيت سلسلة الأدوات
لبناء أي شيء في هذا المستودع يجب أن يكون لديك Rust مثبتًا، بالإضافة إلى إصدارات حديثة من Clang وlibclang وCMake وMake وprotoc وPython (3.11+) و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.
مع مرور الوقت، قد تجد أنك بحاجة إلى بعض أدوات Rust الإضافية مثل taplo لتنسيق الشيفرة.
يجب عليك دائمًا تثبيت أي أدوات Rust تحتاجها والتي قد تؤثر على البناء من cargo بدلاً من مدير حزم نظامك
(مثل apt أو brew). تحتوي مديري الحزم أحيانًا على إصدارات قديمة من هذه الأدوات قد تُعطّل
البناء بسبب مشكلات عدم التوافق.
لتثبيت تبعيات 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
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"
// 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/")
}
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.