Skip to content

README.ar.md

Latest commit

 

History

History
306 lines (207 loc) · 9.47 KB

README.ar.md

File metadata and controls

306 lines (207 loc) · 9.47 KB

Crypto

[English]

هذه المكتبة عبارة عن ربط بين لغة الأسس ومكتبة libcrypto، والتي تحتوي على دوال تشفير لمختلف الخوارزميات.

إضافة المكتبة للمشروع

اشمل "مـتم/طـرفية"؛
اشمل "مـتم/نـص"؛
اشمل "مـحا"؛
مـحا.اشمل_ملف("Alusus/Crypto"، "كـربتو.أسس")؛

import "Srl/Console";
import "Apm";
Apm.importFile("Alusus/Crypto");

مثال

// نقوم بتضمين المكتبات الضرورية
اشمل "مـتم/طـرفية"؛
اشمل "مـتم/نـص"؛
اشمل "مـحا"؛
مـحا.اشمل_ملف("Alusus/Crypto"، "كـربتو.أسس")؛

استخدم مـتم;

// نعرف نص لاختبار تابع التشفير عليه
عرف نص: نـص("مكتبة ربط كـربتو للغة الأسس")؛

// نستدعي تابع التشفير على النص ونقوم بطباعة الناتج
طـرفية.اطبع("%s\ج"، كـربتو.مد5(نص).صوان)؛

// نحمل مفتاحًا رقميا ونستخدمه لإنشاء توقيع رقمي للنص.
عرف مفتاح: سند[كـربتو.مـفتاح_خاص_لامباشر](كـربتو.مـفتاح_خاص_لامباشر.اقرأ_بيم("rsakey"))؛
طـرفية.اطبع("توقيع hmac: %s\ج", كـربتو.وقع(نص, مفتاح, كـربتو.تـلخيص_لامباشر.شا256()).صوان)؛

import "Srl/Console";
import "Apm";
Apm.importFile("Alusus/Crypto");

use Srl;

// نعرف نص لاختبار تابع التشفير عليه
def text: String("Crypto binding for Alusus");

// نستدعي تابع التشفير على النص ونقوم بطباعة الناتج
Console.print("%s\n", Crypto.md5(text).buf);

// نحمل مفتاحًا رقميا ونستخدمه لإنشاء توقيع رقمي للنص.
def pkey: ref[Crypto.EvpPkey](Crypto.EvpPkey.readPem("rsakey"));
Console.print("hmac signature: %s\n", Crypto.sign(text, pkey, Crypto.EvpMd.sha256()).buf);

الأصناف والدوال

مد5 (md5)

دالة مد5(نص: نـص): نـص؛

func md5 (planText: String): String;

تقوم هذه الدالة بتطبيق خوارزمية md5 على نص معطى.

نص (planText): النص الذي نريد تشفيره.

تعيد هذه الدالة نتيجة التشفير، أي النص المشفر.

@تصدير[MD5]
دالة مد5(نص: مؤشر[مـحرف]، طول: صـحيح، نص_مشفر: سند[مصفوفة[مـحرف، 16]]): مؤشر[مـحرف]؛

@expname[MD5]
func md5(plainText: CharsPtr, length: ArchInt, hashedText: ref[array[Char,16]]): CharsPtr;

هذه الدالة يتم استعمالها من قبل الدالة السابقة، حيث أنها تقوم بنفس العمل ولكن يجب تمرير طول النص وذلك لأننا نمرر مؤشر محارف وليس نـص.

نص (plainText): النص بصيغة مؤشر إلى محرف.

طول (length): طول النص.

نص_مشفر (hashedText): المصفوفة التي سيتم تخزين النص المشفر فيها.

رمز_أساس64 (encodeBase64)

دالة رمز_أساس64(مدخلة: مؤشر، حجم_المدخلة: صـحيح_متكيف): نـص؛

دالة رمز_أساس64(مدخلة: نـص): نـص؛

func encodeBase64(input: ptr, inputSize: ArchInt): String;

func encodeBase64(input: String): String;

تقوم هذه الدالة بتطبيق خوارزمية تشفير الأساس 64 على البيانات المعطاة.

الصيغة الأولى من الدالة تستلم مؤشرًا على البيانات المراد تشفيرها وحجمها، بينما تستلم الصيغة الثانية سلسلة محارف. ترجع هذه الدالة النص المشفر.

فك_أساس64 (decodeBase64)

دالة فك_أساس64(مدخلة: نـص، خرج: سند[مؤشر]، حجم_الخرج: سند[صـحيح_متكيف])؛

func decodeBase64(input: String, output: ref[ptr], outputSize: ref[ArchInt])\;

تطبق هذه الدالة خوارزمية فك تشفير الأساس 64 على النص المشفر المعطى.

  • مدخلة (input): النص المشفر بخوارزمية الأساس 64 المراد فك تشفيره.
  • خرج (output): سند لمؤشر يتم تحديثه بمؤشر على البيانات الناتجة من فك التشفير. تحجز الدالة صوانًا للبيانات الناتجة وتترك للمستدعي مسؤولية تحرير الصوان بعد الانتهاء من استخدامه.
  • حجم_الخرج (outputSize): سند لعدد صحيح يستلم حجم البيانات الناتجة من فك التشفير.
دالة فك_أساس64(مدخلة: نـص): نـص؛

func decodeBase64(input: String): String;

مدخلة (input): النص المشفر بخوارزمية الأساس 64 المراد فك تشفيره.

تعيد هذه الدالة النص الغير مشفر.

مـفتاح_خاص_لامباشر (EvpPkey)

صنف يستخدم لتحميل مفتاح خاص (private key) للاستخدام في التشفير اللامباشر (envelope encryption).

اقرأ_بيم (readPem)

دالة اقرأ_بيم(اسم_الملف: مـؤشر_محارف): سند[مـفتاح_خاص_لامباشر]

func readPem(filename: CharsPtr): ref[EvpPkey];

تحمل مفتاحًا خاصًا (private key) من ملف PEM وتعيد سندا للمفتاح.

حرر (free)

عملية هذا.حرر()؛

handler this.free();

تنقص عداد السندات الخاص بالمفتاح وتحرره إذا وصل العداد إلى صفر.

تـلخيص_لامباشر (EvpMd)

هذا الصنف يمثل الخوارزمية المستخدمة لتلخيص البيانات (message digest) عند التشفير. يستخدم هذا الصنف في العمليات التي تطلب تشفيرًا، مثل دالة وقع (sign).

يحتوي هذا الصنف على دالات الإنشاء التالية:

دالة شا224(): سند[تـلخيص_لامباشر]؛
دالة شا256(): سند[تـلخيص_لامباشر]؛
دالة شا512_224(): سند[تـلخيص_لامباشر]؛
دالة شا512_256(): سند[تـلخيص_لامباشر]؛
دالة شا384(): سند[تـلخيص_لامباشر]؛
دالة شا512(): سند[تـلخيص_لامباشر]؛

func sha224(): ref[EvpMd];
func sha256(): ref[EvpMd];
func sha512_224(): ref[EvpMd];
func sha512_256(): ref[EvpMd];
func sha384(): ref[EvpMd];
func sha512(): ref[EvpMd];

وقع (sign)

دالة وقع(بيانات: مـؤشر_محارف، مفتاح: سند[مـفتاح_خاص_لامباشر]، نوع: سند[تـلخيص_لامباشر]): نـص؛

func sign(data: CharsPtr, pkey: ref[EvpPkey], tp: ref[EvpMd]): String;

إنشاء توقيع رقمي لسلسلة المحارف المعطاة.

  • بيانات (data): البيانات المراد إنشاء توقيع رقمي لها.
  • مفتاح (pkey): المفتاح المستخدم لتشفير التوقيع.
  • نوع (tp): نوع التشفير المستخدم.

ترجع الدالة التوقيع بصيغة اساس64 (base64).

دالة وقع(
    مدخلة: مؤشر، حجم_المدخلة: صـحيح_متكيف،
    مفتاح: سند[مـفتاح_خاص_لامباشر]،
    نوع: سند[تـلخيص_لامباشر]،
    خرج: مـؤشر_محارف, حجم_الخرج: سند[صـحيح_متكيف]
)؛

func sign(
    input: ptr, inputSize: ArchInt,
    pkey: ref[EvpPkey],
    tp: ref[EvpMd],
    output: CharsPtr, outputSize: ref[ArchInt]
);

نسخة رقمية من دالة التوقيع، أي أنها تنشئ توقيعا لبيانات رقمية (ليست نصية بالضرورة) وتعيد التوقيع بصيغة رقمية وليس بصيغة أساس64.

  • مدخلة (input): مؤشر على البيانات المراد توقيعها.
  • حجم_المدخلة (inputSize): حجم البيانات المراد توقيعها، بالبايت.
  • مفتاح (pkey): المفتاح المستخدم لتشفير التوقيع.
  • نوع (tp): نوع التشفير المستخدم.
  • خرج (output): مؤشر على صوان لحمل التوقيع الناتج. يجب أن يكون الصوان محجوزًا وبحجم كافي لحمل التوقيع الناتج.
  • حجم_الخرج (outputSize): سند لعدد صحيح يحمل مبدئيًا حجم صوان الخرج. تحدث الدالة قيمة العدد إلى الحجم الفعلي للتوقيع.

الرخصة

حقوق النشر © 2026 سرمد خالد عبد الله

هذا المشروع مرخص بموجب رخصة أباتشي الإصدار 2.0. راجع ملف LICENSE للحصول على التفاصيل.