نظرة عامة

يحتوي libsignal على واجهات برمجة تطبيقات (APIs) مستقلة عن المنصة، تستخدمها عملاء وخوادم Signal الرسمية، وتُقدَّم كمكتبة Java أو Swift أو TypeScript. التطبيقات الأساسية مكتوبة بلغة Rust:

• libsignal-protocol: يطبّق بروتوكول Signal، بما في ذلك Double Ratchet algorithm. وهو بديل عن libsignal-protocol-java وlibsignal-metadata-java.
• signal-crypto: بدائيات تشفيرية مثل AES-GCM. نستخدم مكتبات RustCrypto حيثما أمكن، لكن لدينا أحيانًا احتياجات مختلفة.
• device-transfer: منطق دعم ميزة النقل من جهاز إلى جهاز (device-to-device) في Signal.
• attest: وظائف للإثبات عن بُعد (remote attestation) لـ SGX enclaves ولـ HSMs من جهة الخادم.
• zkgroup: وظائف لـ zero-knowledge groups والميزات ذات الصلة المتوفرة في 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. جميع واجهات البرمجة والتطبيقات قابلة للتغيير دون إشعار مسبق، وكذلك طبقات "الجسر" (bridge) الخاصة بـ JNI وC وإضافات Node. ومع ذلك، فإن التغييرات غير المتوافقة مع الإصدارات السابقة على واجهات Java وSwift وTypeScript وواجهات Rust غير الجسرية ستنعكس في رقم الإصدار على أساس أفضل جهد ممكن، بما في ذلك رفع الحد الأدنى من إصدارات الأدوات المدعومة.

البناء

تثبيت مجموعة الأدوات

لبناء أي شيء في هذا المستودع، يجب أن يكون لديك 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، لدينا سكربت تتم صيانته على أساس أفضل جهد ممكن (best-effort) لإعداد سلسلة أدوات Rust، ويمكنك تشغيله عبر:

$ bin/mac_setup.sh

Rust

البناء والاختبار الأول

يستخدم البناء حاليًا إصدارًا محددًا من مترجم Rust الليلي (nightly)، والذي سيتم تنزيله تلقائيًا بواسطة cargo. لبناء واختبار مكتبات البروتوكول الأساسية:

$ cargo build
...
$ cargo test
...

أدوات Rust إضافية

الأدوات الأساسية المذكورة أعلاه يجب أن تكون كافية لتجهيزك لمعظم أعمال تطوير Rust في libsignal.

في النهاية، قد تجد أنك بحاجة إلى بعض أدوات Rust الإضافية مثل taplo لتنسيق الكود.

يجب عليك دائمًا تثبيت أي أدوات Rust تحتاجها والتي قد تؤثر على البناء من cargo بدلاً من مدير الحزم الخاص بنظامك (مثل apt أو brew). تحتوي مديري الحزم أحيانًا على إصدارات قديمة من هذه الأدوات قد تعطّل البناء بسبب مشكلات عدم التوافق (خاصة 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، وإضافة أهداف Android إلى مترجم Rust، باستخدام

rustup target add armv7-linux-androideabi aarch64-linux-android i686-linux-android x86_64-linux-android

إصدار JDK المدعوم رسميًا لبناءات Android هو JDK 21، لذا تأكد من تثبيت OpenJDK 21 مثلًا، ثم وجّه JAVA_HOME إليه.

يمكنك القيام بذلك بسهولة على macOS عبر:

export JAVA_HOME=$(/usr/libexec/java_home -v 21)

أما على Linux، فتختلف طريقة القيام بذلك حسب التوزيعة. بالنسبة للتوزيعات المبنية على Debian مثل Ubuntu، يمكنك استخدام:

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 للبناء دون تصفية سجلات مستوى التصحيح (debug) والتوسع (verbose) من Rust، و-P jniTypeTagging لتفعيل فحوصات إضافية في كود جسر JNI في Rust.

بدلاً من ذلك، يتوفر نظام بناء يستخدم Docker:

$ cd java
$ make

عند كشف واجهات برمجة جديدة لـ Java، ستحتاج إلى تشغيل rust/bridge/jni/bin/gen_java_decl.py بالإضافة إلى إعادة البناء. يتطلب ذلك تثبيت أداة Rust cbindgen، كما هو موضح أعلاه.

الاستخدام كمكتبة

تنشر Signal حزم Java لاستخدامها الخاص، تحت الأسماء org.signal:libsignal-server وorg.signal:libsignal-client وorg.signal:libsignal-android. تحتوي libsignal-client وlibsignal-server على مكتبات أصلية (native) لنظام Linux بنكهة Debian على x86_64، بالإضافة إلى Windows (x86_64) وmacOS (x86_64 وarm64). تحتوي libsignal-android على مكتبات أصلية لـ Android على armeabi-v7a وarm64-v8a وx86 وx86_64. توجد هذه الحزم في مستودع 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 بدلاً من ذلك.

عند البناء لنظام Android، تحتاج إلى كل من libsignal-android وlibsignal-client، لكن مكتبات Windows وmacOS في libsignal-client لن تُستبعد تلقائيًا من تطبيقك النهائي. يمكنك استبعادها صراحةً باستخدام packaging:

android {
  // ...
  packaging {
    resources {
      excludes += setOf("libsignal_jni*.dylib", "signal_jni*.dll")
    }
  }
  // ...
}

يمكنك أيضًا استبعاد libsignal_jni_testing.so إذا كنت لا تخطط لاستخدام أي من واجهات البرمجة المخصصة لاختبار العملاء.

اختبار بناء محلي مع Signal-Android

يحتوي ملف gradle.properties الخاص بـ Signal-Android على سطر مُعلَّق (commented-out) لتضمين libsignal كجزء من البناء. قم بإلغاء تعليق هذا السطر واضبط المسار؛ ويمكنك اختياريًا تقييد البنيات التي تريد البناء لها بإضافة androidArchs=aarch64 إلى ملف gradle.properties الخاص بـ libsignal. (مجموعة البنيات المعترف بها موجودة في java/build_jni.sh.) إذا كنت تستخدم بيئة تطوير متكاملة (IDE)، فستحتاج إلى إعادة استيراد بنية Gradle في هذه المرحلة. عند الانتهاء، تراجع عن التغييرات في ملف gradle.properties الخاص بتطبيق Android وأعد الاستيراد مرة أخرى.

لاحظ أن هذا لا يستورد أجزاء Rust من المشروع إلى بيئة التطوير المتكاملة. القيام بذلك في بيئة تطوير متعددة اللغات مثل IDEA ممكن، لكنه صعب ومتعب؛ فاعتبارًا من عام 2025، الطريقة الأكثر موثوقية هي فتح مشروع Android أولاً، ثم إضافة الدليل الجذري لمستودع libsignal كمشروع Rust ثانيًا (مع تضمين الدليل العلوي فقط)، وبعد ذلك فقط إجراء التغييرات على gradle.properties.

Swift

للتعرف على عملية بناء Swift، انظر swift/README.md

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، ستحتاج إلى تشغيل just generate-node بالإضافة إلى إعادة البناء.

NPM

تنشر Signal حزمة NPM @signalapp/libsignal-client لاستخدامها الخاص، وتتضمن مكتبات أصلية لأنظمة Windows وmacOS وLinux بنكهة Debian. يتم تضمين بنيات x64 وarm64 لجميع المنصات الثلاث، لكن بنيات arm64 لنظامي Windows وLinux تُعتبر تجريبية، نظرًا لعدم وجود بنيات رسمية من Signal لهذه البنيات.

اختبار بناء محلي مع Signal-Desktop

بعد تشغيل جميع أوامر البناء المذكورة أعلاه، اضبط تبعية @signalapp/libsignal-client في ملف package.json الخاص بتطبيق Desktop على "link:path/to/libsignal/node" وشغّل pnpm install. عند الانتهاء، تراجع عن التغييرات في package.json وشغّل pnpm install مرة أخرى.

المساهمات

تقبل Signal المساهمات الخارجية في هذا المشروع. ومع ذلك، ما لم يكن التغيير بسيطًا وسهل الفهم، على سبيل المثال إصلاح خطأ برمجي أو مشكلة قابلية نقل (portability)، أو إضافة اختبار جديد، أو تحسين الأداء، فافتح أولاً issue (تقرير مشكلة) لمناقشة التغيير الذي تنوي إجراؤه، حيث لا يمكن قبول جميع التغييرات.

قد تظل المساهمات التي لن تُستخدم مباشرة من قبل أحد تطبيقات Signal الرسمية محل نظر، ولكن فقط إذا لم تشكّل عبء صيانة غير مبرر أو تتعارض مع أهداف المشروع.

يُطلب توقيع CLA (اتفاقية ترخيص المساهم) لجميع المساهمات.

تنسيق الكود والإقرارات

يمكنك تشغيل أداة التنسيق (styler) على المشروع بأكمله عن طريق تشغيل:

just format-all

يمكنك تشغيل اختبارات أكثر شمولاً بالإضافة إلى أدوات الفحص (linters) وclippy عن طريق تشغيل:

just check-pre-commit

عند إنشاء طلب سحب (PR) يعدّل التبعيات، ستحتاج إلى إعادة توليد ملفات الإقرارات الخاصة بنا. انظر acknowledgments/README.md.

أمور قانونية

إشعار التشفير

يتضمن هذا التوزيع برامج تشفير. قد تفرض الدولة التي تقيم فيها حاليًا قيودًا على استيراد برامج التشفير أو حيازتها أو استخدامها و/أو إعادة تصديرها إلى دولة أخرى. قبل استخدام أي برنامج تشفير، يرجى مراجعة قوانين بلدك ولوائحه وسياساته المتعلقة باستيراد برامج التشفير أو حيازتها أو استخدامها وإعادة تصديرها، للتأكد مما إذا كان ذلك مسموحًا به. راجع http://www.wassenaar.org/ لمزيد من المعلومات.

صنّفت وزارة التجارة التابعة للحكومة الأمريكية، مكتب الصناعة والأمن (BIS)، هذا البرنامج ضمن رقم مراقبة السلع التصديرية (ECCN) 5D002.C.1، والذي يشمل برامج أمن المعلومات التي تستخدم أو تنفّذ وظائف تشفيرية باستخدام خوارزميات غير متماثلة. إن شكل وطريقة هذا التوزيع يجعلانه مؤهلاً للتصدير بموجب استثناء الترخيص ENC Technology Software Unrestricted (TSU) (انظر لوائح إدارة التصدير الصادرة عن BIS، القسم 740.13) لكل من الكود الهدف (object code) والكود المصدري (source code).

الترخيص

حقوق النشر 2020-2026 Signal Messenger, LLC

مرخّص بموجب GNU AGPLv3: https://www.gnu.org/licenses/agpl-3.0.html