sodium_compat
Version 2.1.0
Sodium Compat عبارة عن بوليفيل PHP نقي لمكتبة تشفير الصوديوم (libsodium)، وهو امتداد أساسي في PHP 7.2.0+ ومتوفر في PECL.
إذا كان لديك امتداد PHP مثبتًا، فسوف يستخدم Sodium Compat امتداد PHP بشكل انتهازي وشفاف بدلاً من تطبيقنا.
كان Sodium_compat v1.21.0 هو الإصدار v1.x الأخير من الفرع الرئيسي. من الآن فصاعدًا، ستكون جميع الإصدارات المستقبلية التي تدعم PHP 5.2 - 8.0 والأعداد الصحيحة 32 بت موجودة في الفرع v1.x
ستستمر الإصدارات الأحدث من Sodium_compat (أي v2.0.0) في العيش في الفرع الرئيسي، ما لم تكن هناك حاجة إلى إصدار رئيسي جديد. الهدف من هذا العمل هو تحسين إمكانية قراءة التعليمات البرمجية والأداء، مع تقليل التعليمات البرمجية النمطية.
في حالة الشك، ارجع إلى ملف README الموجود في الفرع الرئيسي للحصول على أحدث معلومات الإصدار.
| إصدار الصوديوم_المتوافق | إصدارات PHP المدعومة | دعم 32 بت؟ | فرع |
|---|---|---|---|
v1.xy | 5.2.4 - الأحدث | نعم | v1.x |
v2.xy | 8.1 - الأحدث | لا | يتقن |
إذا كنت بحاجة إلى دعم PHP 32 بت ( PHP_INT_SIZE == 4 )، فتابع استخدام Sodium_compat v1.x. إذا كنت تريد تحسين الأداء وتبعيات أصغر، استخدم v2.x.
نوصي المكتبات والأطر بتعيين قيد إصدار الملحن على النحو التالي:
{
"require" : {
/* ... */
"paragonie/sodium_compat" : ">= 1"
/* ... */
}
}وعلى العكس من ذلك، يجب أن تحدد التطبيقات الإصدار الفعلي الذي يهمها وعمليات نشرها.
لم يتم تدقيق مكتبة التشفير هذه رسميًا من قبل جهة خارجية مستقلة متخصصة في التشفير أو تحليل التشفير.
إذا كنت تحتاج إلى مثل هذا التدقيق قبل أن تتمكن من استخدام Sodium_compat في مشاريعك والحصول على الأموال اللازمة لمثل هذا التدقيق، فيرجى فتح مشكلة أو الاتصال security at paragonie dot com حتى نتمكن من المساعدة في بدء العمل.
ومع ذلك، فقد تم اعتماد Sodium_compat من خلال مشاريع مفتوحة المصدر رفيعة المستوى، مثل Joomla! و ماجنتو. علاوة على ذلك، تم تطوير Sodium_compat بواسطة Paragonمبادرة المؤسسات، وهي شركة متخصصة في تطوير PHP الآمن وتشفير PHP، وتمت مراجعتها بشكل غير رسمي من قبل العديد من خبراء الأمان الآخرين المتخصصين أيضًا في PHP.
إذا كنت ترغب في معرفة المزيد حول إجراءات الأمان الدفاعية التي اتخذناها لمنع الصوديوم_كومبات من أن يكون مصدرًا للثغرات الأمنية في أنظمتك، فيرجى قراءة تطوير PHP الآمن المشفر .
إذا كنت تستخدم الملحن:
composer require paragonie/sodium_compat إذا كنت لا تستخدم Composer، فقم بتنزيل إصدار tarball (الذي يجب أن يكون موقعًا باستخدام مفتاح GnuPG العام الخاص بنا)، واستخرج محتوياته، ثم قم بتضمين البرنامج النصي autoload.php الخاص بنا في مشروعك.
<?php
require_once " /path/to/sodium_compat/autoload.php " ;منذ الإصدار 1.3.0، تتضمن إصدارات Sodium_compat أرشيف PHP (ملف .phar) وتوقيع GPG المرتبط. أولاً، قم بتنزيل كلا الملفين والتحقق منهما باستخدام مفتاح GPG العام الخاص بنا، كما يلي:
# Getting our public key from the keyserver:
gpg --fingerprint 7F52D5C61D1255C731362E826B97A1C2826404DA
if [ $? -ne 0 ] ; then
echo -e " 33[33mDownloading PGP Public Key... 33[0m "
gpg --keyserver pgp.mit.edu --recv-keys 7F52D5C61D1255C731362E826B97A1C2826404DA
# Security <[email protected]>
gpg --fingerprint 7F52D5C61D1255C731362E826B97A1C2826404DA
if [ $? -ne 0 ] ; then
echo -e " 33[31mCould not download PGP public key for verification 33[0m "
exit 1
fi
fi
# Verifying the PHP Archive
gpg --verify sodium-compat.phar.sig sodium-compat.pharالآن، قم ببساطة بتضمين ملف .phar هذا في تطبيقك.
<?php
require_once " /path/to/sodium-compat.phar " ;يتوفر الدعم التجاري لليبسوديوم من العديد من البائعين. إذا كنت بحاجة إلى مساعدة في استخدام Sodium_compat في أحد مشاريعك، فاتصل بمؤسسات مبادرة Paragon.
سيتم تسهيل التقرير غير التجاري من خلال إصدارات Github. نحن لا نقدم أي ضمانات بشأن مدى توفرنا لحل الأسئلة المتعلقة بدمج Sodium_compat في برامج الطرف الثالث مجانًا، ولكننا سنسعى جاهدين لإصلاح أي أخطاء (متعلقة بالأمان أو غير ذلك) في مكتبتنا.
إذا كانت شركتك تستخدم هذه المكتبة في منتجاتها أو خدماتها، فقد تكون مهتمًا بشراء عقد دعم من Paragon Innovation Enterprises.
وفقًا للتصويت الثاني على libsodium RFC، يستخدم PHP 7.2 sodium_* بدلاً من Sodium* .
<?php
require_once " /path/to/sodium_compat/autoload.php " ;
$ alice_kp = sodium_crypto_sign_keypair ();
$ alice_sk = sodium_crypto_sign_secretkey ( $ alice_kp );
$ alice_pk = sodium_crypto_sign_publickey ( $ alice_kp );
$ message = ' This is a test message. ' ;
$ signature = sodium_crypto_sign_detached ( $ message , $ alice_sk );
if ( sodium_crypto_sign_verify_detached ( $ signature , $ message , $ alice_pk )) {
echo ' OK ' , PHP_EOL ;
} else {
throw new Exception ( ' Invalid signature ' );
} إذا كان المستخدمون لديك يستخدمون PHP <5.3، أو كنت تريد كتابة تعليمات برمجية ستعمل سواء كان امتداد PECL متاحًا أم لا، فستحتاج إلى استخدام فئة ParagonIE_Sodium_Compat لمعظم احتياجات libsodium الخاصة بك.
المثال أعلاه مكتوب للاستخدام العام:
<?php
require_once " /path/to/sodium_compat/autoload.php " ;
$ alice_kp = ParagonIE_Sodium_Compat:: crypto_sign_keypair ();
$ alice_sk = ParagonIE_Sodium_Compat:: crypto_sign_secretkey ( $ alice_kp );
$ alice_pk = ParagonIE_Sodium_Compat:: crypto_sign_publickey ( $ alice_kp );
$ message = ' This is a test message. ' ;
$ signature = ParagonIE_Sodium_Compat:: crypto_sign_detached ( $ message , $ alice_sk );
if (ParagonIE_Sodium_Compat:: crypto_sign_verify_detached ( $ signature , $ message , $ alice_pk )) {
echo ' OK ' , PHP_EOL ;
} else {
throw new Exception ( ' Invalid signature ' );
} بشكل عام: إذا قمت باستبدال sodium_ بـ ParagonIE_Sodium_Compat:: ، فإن أي كود مكتوب بالفعل لامتداد libsodium PHP يجب أن يعمل مع polyfill الخاص بنا دون تغييرات إضافية في التعليمات البرمجية.
نظرًا لأن هذا لا يتطلب مساحة اسم، فسيتم عرض واجهة برمجة التطبيقات هذه في PHP 5.2.
منذ الإصدار 0.7.0، لدينا واجهة برمجة تطبيقات خاصة بنا ذات مساحة اسم ( ParagonIESodium* ) للسماح بالإيجاز في البرامج التي تستخدم PHP 5.3+. يعد هذا مفيدًا إذا كنت تريد استخدام ميزات تشفير الملفات لدينا دون كتابة ParagonIE_Sodium_File في كل مرة. لا يتم عرض هذا في PHP <5.3، لذا إذا كان مشروعك يدعم PHP <5.3، فاستخدم طريقة الشرطة السفلية بدلاً من ذلك.
لمعرفة كيفية استخدام Libsodium، اقرأ استخدام Libsodium في مشاريع PHP .
هناك ثلاث طرق لجعلها سريعة:
ParagonIE_Sodium_Compat::$fastMult = true; دون الإضرار بأمان مفاتيح التشفير الخاصة بك. إذا لم يكن المعالج الخاص بك آمنًا، فحدد ما إذا كنت تريد السرعة أو الأمان لأنه لا يمكنك الحصول على كليهما. منذ الإصدار 1.8، يمكنك استخدام التابع polyfill_is_fast() الثابت لتحديد ما إذا كان Sodium_compat سيكون بطيئًا في وقت التشغيل.
<?php
if (ParagonIE_Sodium_Compat:: polyfill_is_fast ()) {
// Use libsodium now
$ process -> execute ();
} else {
// Defer to a cron job or other sort of asynchronous process
$ process -> enqueue ();
}أولاً، ستحتاج إلى قراءة المرجع السريع لـ Libsodium. يهدف إلى الإجابة على "ما الوظيفة التي يجب أن أستخدمها في [مشكلة شائعة]؟".
إذا لم تجد الإجابات في صفحة المرجع السريع، فراجع استخدام Libsodium في مشاريع PHP .
أخيرًا، تحتوي أيضًا وثائق libsodium الرسمية (التي تمت كتابتها لمكتبة C، وليس لمكتبة PHP) على الكثير من المعلومات التقنية الثاقبة التي قد تجدها مفيدة.
القراءة الموصى بها: مرجع سريع لليبسوديوم
crypto_auth()crypto_auth_verify()crypto_box()crypto_box_open()crypto_scalarmult()crypto_secretbox()crypto_secretbox_open()crypto_sign()crypto_sign_open()crypto_aead_aegis128l_encrypt()crypto_aead_aegis128l_decrypt()crypto_aead_aegis256_encrypt()crypto_aead_aegis256_decrypt()crypto_aead_aes256gcm_encrypt()crypto_aead_aes256gcm_decrypt()crypto_aead_chacha20poly1305_encrypt()crypto_aead_chacha20poly1305_decrypt()crypto_aead_chacha20poly1305_ietf_encrypt()crypto_aead_chacha20poly1305_ietf_decrypt()crypto_aead_xchacha20poly1305_ietf_encrypt()crypto_aead_xchacha20poly1305_ietf_decrypt()crypto_box_xchacha20poly1305()crypto_box_xchacha20poly1305_open()crypto_box_seal()crypto_box_seal_open()crypto_generichash()crypto_generichash_init()crypto_generichash_update()crypto_generichash_final()crypto_kx()crypto_secretbox_xchacha20poly1305()crypto_secretbox_xchacha20poly1305_open()crypto_shorthash()crypto_sign_detached()crypto_sign_ed25519_pk_to_curve25519()crypto_sign_ed25519_sk_to_curve25519()crypto_sign_verify_detached()crypto_core_ristretto255_add()crypto_core_ristretto255_from_hash()crypto_core_ristretto255_is_valid_point()crypto_core_ristretto255_random()crypto_core_ristretto255_scalar_add()crypto_core_ristretto255_scalar_complement()crypto_core_ristretto255_scalar_invert()crypto_core_ristretto255_scalar_mul()crypto_core_ristretto255_scalar_negate()crypto_core_ristretto255_scalar_random()crypto_core_ristretto255_scalar_reduce()crypto_core_ristretto255_scalar_sub()crypto_core_ristretto255_sub()crypto_scalarmult_ristretto255_base()crypto_scalarmult_ristretto255()crypto_stream()crypto_stream_keygen()crypto_stream_xor()crypto_stream_xchacha20()crypto_stream_xchacha20_keygen()crypto_stream_xchacha20_xor()crypto_stream_xchacha20_xor_ic()crypto_*_keypair() )add()base642bin()bin2base64()bin2hex()hex2bin()crypto_kdf_derive_from_key()crypto_kx_client_session_keys()crypto_kx_server_session_keys()crypto_secretstream_xchacha20poly1305_init_push()crypto_secretstream_xchacha20poly1305_push()crypto_secretstream_xchacha20poly1305_init_pull()crypto_secretstream_xchacha20poly1305_pull()crypto_secretstream_xchacha20poly1305_rekey()pad()unpad() sodium_memzero() - على الرغم من أننا كشفنا عن نقطة نهاية واجهة برمجة التطبيقات هذه، إلا أننا لا نستطيع الاعتماد على إزالة المخازن المؤقتة من PHP.
إذا كان ملحق PHP مثبتًا لديك، فسيستخدم Sodium_compat التطبيق الأصلي لتصفية السلسلة المتوفرة. وإلا فإنه سوف يرمي SodiumException .
sodium_crypto_pwhash() - ليس من الممكن إضافة polyfill scrypt أو Argon2 إلى PHP والحصول على أداء معقول. سيشعر المستخدمون بالتحفيز لاختيار المعلمات التي تعمل على خفض مستوى الأمان لتجنب هجمات رفض الخدمة (DoS).
الخطوة الوحيدة الفائزة هي عدم اللعب.
إذا تم تثبيت ext/sodium أو ext/libsodium، فسوف تفشل طرق واجهة برمجة التطبيقات هذه في الامتداد. بخلاف ذلك، ستطرح مكتبة polyfill الخاصة بنا استثناء SodiumException .
لاكتشاف دعم Argon2i في وقت التشغيل، استخدم ParagonIE_Sodium_Compat::crypto_pwhash_is_available() ، الذي يُرجع قيمة منطقية ( TRUE أو FALSE ).
لم يتم تضمين واجهة برمجة تطبيقات HKDF الخاصة بـ Libsodium ( crypto_kdf_hkdf_*() ) لأن PHP لديها ميزات HMAC الخاصة بها ولم تكن ضرورية.
بالنسبة لمستخدمي Sodium_compat والذين يستخدمون PHPCompatibility في عملية CI الخاصة بهم، هناك الآن مجموعة قواعد مخصصة متاحة والتي يمكن استخدامها لمنع النتائج الإيجابية الخاطئة التي يتم طرحها بواسطة PHPCompatibility لوظيفة PHP الأصلية التي يتم ملؤها بواسطة هذا الريبو.
يمكنك العثور على الريبو لمجموعة قواعد PHPCompatibilityParagonieSodiumCompat هنا على Github وعلى Packagist.
