Halite

Halite هي واجهة تشفير عالية المستوى تعتمد على libsodium في جميع عمليات التشفير الأساسية التي تقوم بها.

تم إنشاء Halite بواسطة Paragon Initiative Enterprises كـ نتيجة لجهودنا المستمرة لتحسين النظام البيئي وجعل التشفير في PHP أكثر أمانًا وأسهل في التنفيذ.

يمكنك قراءة وثائق Halite على الإنترنت.

تم إصدار Halite بموجب رخصة Mozilla Public License 2.0. تتوفر تراخيص تجارية من Paragon Initiative Enterprises إذا كنت ترغب في توسيع Halite دون جعل أعمالك المشتقة متاحة بموجب شروط MPL.

إذا كنت راضيًا عن شروط برمجيات MPL الخاصة بتطبيقات الويب الخلفية (backend) ولكنك ترغب في شراء عقد دعم لتطبيقك الذي يستخدم Halite، فتلك العقود متاحة أيضًا من Paragon Initiative Enterprises.

مهم: كانت الإصدارات الأقدم من Halite متاحة بموجب رخصة GNU Public License الإصدار 3 (GPLv3). فقط Halite 4.0.1 والإصدارات الأحدث متاحة بموجب شروط Mozilla Public License.

تثبيت Halite

قبل أن تتمكن من استخدام Halite، يجب عليك اختيار إصدار يناسب متطلبات مشروعك. الاختلافات بين متطلبات الإصدارات المتاحة من Halite موضحة بإيجاز أدناه.

ملاحظة: يعمل Halite 5.0.x على PHP 8.0، لكن الأداء أسوأ منه على PHP 8.1.

إذا كنت بحاجة إلى إصدار من Halite قبل 5.1، فراجع الوثائق ذات الصلة بذلك الفرع تحديدًا.

لتثبيت Halite، يجب عليك أولاً تثبيت libsodium. قد تحتاج إلى امتداد PHP وقد لا تحتاجه. بالنسبة لمعظم المستخدمين، هذا يعني تشغيل...

sudo apt-get install php7.2-sodium

...أو أمرًا مكافئًا لنظام التشغيل وإصدار PHP لديك.

إذا كنت عالقًا، فقد يكون هذا الدليل التفصيلي المقدم من @aolko مفيدًا.

بمجرد تثبيت المتطلبات الأساسية، قم بتثبيت Halite عبر Composer:

composer require paragonie/halite:^5

الدعم التجاري للإصدارات الأقدم من Halite

الدعم المجاني (gratis) لـ Halite يمتد فقط إلى أحدث إصدار رئيسي (حاليًا 5).

إذا كانت شركتك تحتاج إلى دعم لإصدار أقدم من Halite، تواصل مع Paragon Initiative Enterprises للاستفسار عن خيارات الدعم التجاري.

إذا كنت بحاجة إلى طريقة سهلة للترحيل من الإصدارات الأقدم من Halite، فاطلع على halite-legacy.

استخدام Halite في مشروعك

اطلع على الوثائق. صُممت واجهة برمجة التطبيقات الأساسية في Halite لتحقيق البساطة:

• التشفير
  • المتماثل
    • Symmetric\Crypto::encrypt(HiddenString, EncryptionKey): string
    • Symmetric\Crypto::encryptWithAD(HiddenString, EncryptionKey, string): string
    • Symmetric\Crypto::decrypt(string, ):

مثال: تشفير رسالة وفك تشفيرها

أولاً، أنشئ مفتاحًا واحفظه مرة واحدة فقط:

<?php
use ParagonIE\Halite\KeyFactory;

$encKey = KeyFactory::generateEncryptionKey();
KeyFactory::save($encKey, '/path/outside/webroot/encryption.key');

وبعد ذلك يمكنك تشفير/فك تشفير الرسائل كما يلي:

<?php
use ParagonIE\Halite\KeyFactory;
use ParagonIE\Halite\Symmetric\Crypto as Symmetric;
use ParagonIE\HiddenString\HiddenString;

$encryptionKey = KeyFactory::loadEncryptionKey('/path/outside/webroot/encryption.key');

$message = new HiddenString('This is a confidential message for your eyes only.');
$ciphertext = Symmetric::encrypt($message, $encryptionKey);

$decrypted = Symmetric::decrypt($ciphertext, $encryptionKey);

var_dump($decrypted->getString() === $message->getString()); // bool(true)

يجب أن يُنتج هذا شيئًا مشابهًا لما يلي:

MUIDAEpQznohvNlQ-ZRk-ZZ59Mmox75D_FgAIrXY2cUfStoeL-GIeAe0m-uaeURQdPsVmc5XxRw3-2x5ZAsZH_es37qqFuLFjUI-XK9uG0s30YTsorWfpHdbnqzhRuUOI09c-cKrfMQkNBNm0dDDwZazjTC48zWikRHSHXg8NXerVDebzng1aufc_S-osI_zQuLbZDODujEnpbPZhMMcm4-SWuyVXcBPdGZolJyT

المفاتيح التشفيرية في Halite

مهم: يعمل Halite مع كائنات Key، وليس سلاسل نصية.

إذا حاولت استخدام echo على كائن مفتاح، فستحصل على سلسلة فارغة بدلاً من محتوياته. وإذا حاولت استخدام var_dump() على كائن مفتاح، ستحصل فقط على بعض المعلومات حول نوع المفتاح.

يجب عليك استدعاء $obj->getRawKeyMaterial() صراحةً إذا أردت فحص المحتويات الثنائية الخام للمفتاح. هذا غير موصى به لمعظم حالات الاستخدام.

مثال: إنشاء مفتاح من كلمة مرور

<?php
use ParagonIE\Halite\KeyFactory;
use ParagonIE\HiddenString\HiddenString;

$passwd = new HiddenString('correct horse battery staple');
// Use random_bytes(16); to generate the salt:
$salt = "\xdd\x7b\x1e\x38\x75\x9f\x72\x86\x0a\xe9\xc8\x58\xf6\x16\x0d\x3b";

$encryptionKey = KeyFactory::deriveEncryptionKey($passwd, $salt);

يمكن استخدام المفتاح المشتق من كلمة مرور بدلاً من المفتاح المُولَّد عشوائيًا.

مثال: تشفير ملف كبير على نظام بذاكرة منخفضة

يتضمن Halite فئة تشفير ملفات تستخدم واجهة برمجة تطبيقات دفق (streaming API) للسماح بتشفير الملفات الكبيرة (مثل ملفات بحجم غيغابايت) على نظام بذاكرة متاحة قليلة جدًا (أي أقل من 8 ميجابايت).

<?php
use ParagonIE\Halite\File;
use ParagonIE\Halite\KeyFactory;

$encryptionKey = KeyFactory::loadEncryptionKey('/path/outside/webroot/encryption.key');

File::encrypt('input.txt', 'output.txt', $encryptionKey);

مشكلات الدعم الشائعة

استثناء SodiumException غير ملتقط: Cannot Wipe Memory

PHP Fatal error: Uncaught SodiumException: This is not implemented, as it is not possible to securely wipe memory from PHP

الحل لهذه المشكلة هو التأكد من تثبيت/تمكين libsodium. راجع ما ورد أعلاه في هذا README لمزيد من المعلومات.

عقود الدعم

إذا كانت شركتك تستخدم هذه المكتبة في منتجاتها أو خدماتها، فقد يهمك شراء عقد دعم من Paragon Initiative Enterprises.