نظرة عامة

يحتوي 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 add-on. ومع ذلك، فإن التغييرات غير المتوافقة مع الإصدارات السابقة على واجهات 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، لدينا سكربت يتم صيانته على أساس بذل أفضل جهد لإعداد سلسلة أدوات Rust يمكنك تشغيله عبر:

$ bin/mac_setup.sh

Rust

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

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

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

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

يجب أن تُعدّك الأدوات الأساسية أعلاه لمعظم تطوير libsignal بلغة Rust.

في النهاية، قد تجد أنك بحاجة إلى بعض أدوات 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 للاستخدام مع مديري إصدارات وقت التشغيل.

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

لبناء jar وaar الخاصين بـ Java/Android، وتشغيل الاختبارات:

$ cd java
$ ./gradlew test
$ ./gradlew build # if you need AAR outputs

يمكنك تمرير -P debugLevelLogs إلى Gradle للبناء دون تصفية سجلات مستوى debug وverbose من Rust، و-P jniTypeTagging لتمكين فحوصات إضافية في كود جسر Rust JNI.

بدلاً من ذلك، يتوفر نظام بناء باستخدام 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 على مكتبات أصلية لـ Debian-flavored x86_64 Linux وكذلك Windows (x86_64) وmacOS (x86_64 وarm64). تحتوي libsignal-android على مكتبات أصلية لـ armeabi-v7a وarm64-v8a وx86 و x86_64 Android. توجد هذه في مستودع 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 على سطر معلّق لضم 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 وDebian-flavored Linux. يتم تضمين عمليات بناء 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 مساهمات خارجية لهذا المشروع. ومع ذلك، ما لم يكن التغيير بسيطًا وسهل الفهم، مثل إصلاح خطأ أو مشكلة قابلية نقل، أو إضافة اختبار جديد، أو تحسين الأداء، فافتح أولاً مشكلة (issue) لمناقشة التغيير الذي تنوي القيام به لأن ليس كل التغييرات يمكن قبولها.

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

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

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

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

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) لكل من الكود الكائني والكود المصدري.

الترخيص

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

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