الاسم¶

EVP_PKEY_Q_keygen, EVP_PKEY_keygen_init, EVP_PKEY_paramgen_init, EVP_PKEY_generate, EVP_PKEY_CTX_set_cb, EVP_PKEY_CTX_get_cb, EVP_PKEY_CTX_get_keygen_info, EVP_PKEY_CTX_set_app_data, EVP_PKEY_CTX_get_app_data, EVP_PKEY_gen_cb, EVP_PKEY_paramgen, EVP_PKEY_keygen - دوال توليد المفتاح والمعامل والتحقق

موجز¶

 #include <openssl/evp.h>
 EVP_PKEY *EVP_PKEY_Q_keygen(OSSL_LIB_CTX *libctx, const char *propq,
                             const char *type, ...);
 int EVP_PKEY_keygen_init(EVP_PKEY_CTX *ctx);
 int EVP_PKEY_paramgen_init(EVP_PKEY_CTX *ctx);
 int EVP_PKEY_generate(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey);
 int EVP_PKEY_paramgen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey);
 int EVP_PKEY_keygen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey);
 typedef int EVP_PKEY_gen_cb(EVP_PKEY_CTX *ctx);
 void EVP_PKEY_CTX_set_cb(EVP_PKEY_CTX *ctx, EVP_PKEY_gen_cb *cb);
 EVP_PKEY_gen_cb *EVP_PKEY_CTX_get_cb(EVP_PKEY_CTX *ctx);
 int EVP_PKEY_CTX_get_keygen_info(EVP_PKEY_CTX *ctx, int idx);
 void EVP_PKEY_CTX_set_app_data(EVP_PKEY_CTX *ctx, void *data);
 void *EVP_PKEY_CTX_get_app_data(EVP_PKEY_CTX *ctx);

الوصف¶

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

للسماح بمرونة بكل ما وُصف للتو، يُقسم توليد معامل المفتاح والمفتاح إلى تهيئة لسياق خوارزمية المفتاح، ودوال لتعيين المعاملات المقدمة من المستخدم، وأخيرًا دالة توليد معامل المفتاح أو المفتاح نفسها.

يجب إنشاء سياق خوارزمية المفتاح باستخدام EVP_PKEY_CTX_new(3) أو متغيراتها، انظر ذلك الدليل للتفاصيل.

EVP_PKEY_keygen_init() تُهيئ سياق خوارزمية مفتاح عام ctx لعملية توليد مفتاح.

EVP_PKEY_paramgen_init() مشابهة لـ EVP_PKEY_keygen_init() باستثناء أن معاملات المفتاح تُولَّد.

بعد التهيئة، يمكن تقديم معاملات التوليد باستخدام EVP_PKEY_CTX_ctrl(3) أو EVP_PKEY_CTX_set_params(3)، أو أي دالة أخرى موصوفة في تلك الأدلة.

EVP_PKEY_generate() تُنفذ عملية التوليد، وتُكتب معاملات المفتاح أو المفتاح الناتج إلى *ppkey. إذا كان *ppkey NULL عند استدعاء هذه الدالة، فسيُخصص، ويجب تحريره بواسطة المستدعي عندما لا يعود مفيدًا، باستخدام EVP_PKEY_free(3).

EVP_PKEY_paramgen() و EVP_PKEY_keygen() تفعلان نفس الشيء تمامًا مثل EVP_PKEY_generate()، بعد التحقق من أن EVP_PKEY_paramgen_init() أو EVP_PKEY_keygen_init() المقابلة استُخدمت لتهيئة ctx. هذه دوال أقدم محفوظة للتوافق مع الإصدارات السابقة. من الآمن استخدام EVP_PKEY_generate() بدلاً منها.

الدالة EVP_PKEY_set_cb() تعين استدعاء توليد المفتاح أو المعامل إلى cb. الدالة EVP_PKEY_CTX_get_cb() تُرجع استدعاء توليد المفتاح أو المعامل.

الدالة EVP_PKEY_CTX_get_keygen_info() تُرجع معاملات مرتبطة بعملية التوليد. إذا كان idx هو -1، يُعاد العدد الإجمالي للمعاملات المتاحة. أي قيمة غير سالبة تُعيد قيمة ذلك المعامل. يجب استدعاء EVP_PKEY_CTX_gen_keygen_info() بقيمة غير سالبة لـ idx فقط داخل استدعاء التوليد.

إذا أعاد الاستدعاء 0، فتُلغى عملية توليد المفتاح ويحدث خطأ. قد يحدث هذا أثناء عملية تستغرق وقتًا حيث ينقر المستخدم على زر "إلغاء".

الدالتان EVP_PKEY_CTX_set_app_data() و EVP_PKEY_CTX_get_app_data() تربطان مؤشرًا معتمًا محددًا من التطبيق بكائن EVP_PKEY_CTX.

هذا المؤشر لا يُفسر بواسطة المكتبة وهو محجوز بالكامل لاستخدام التطبيق. قد يُستخدم لتخزين سياق أو حالة عشوائية تحتاج إلى أن تكون قابلة للوصول أينما كان EVP_PKEY_CTX المقابل متاحًا.

EVP_PKEY_Q_keygen() تُجرد من الاستخدام الصريح لـ EVP_PKEY_CTX مع توفير طريقة 'سريعة' ولكن محدودة لتوليد زوج مفاتيح غير متماثل جديد. توفر اختصارات للحالات البسيطة والشائعة لتوليد المفاتيح. كالمعتاد، يمكن تقديم سياق المكتبة libctx واستعلام الخاصية propq لجلب الخوارزميات من المزودين. إذا كان type هو "RSA"، يجب تقديم معامل من نوع size_t لتحديد حجم مفتاح RSA. إذا كان type هو "EC"، يجب تقديم معامل سلسلة محارف لتحديد اسم منحنى EC. إذا كان type هو: "ED25519", "ED448", "SM2", "X25519", "X448", "ML-DSA-44", "ML-DSA-65", "ML-DSA-87", "ML-KEM-512", "ML-KEM-768"، أو "ML-KEM-1024" فلا حاجة لمعاملات إضافية. قد تكون أنواع مفاتيح أخرى ممكنة إذا قدمها المزودون المحملون. قد تكون EVP_PKEY_Q_keygen() قابلة للاستخدام مع أنواع المفاتيح هذه طالما أنها لا تتطلب معاملات إضافية.

القيم المُرجعة¶

EVP_PKEY_keygen_init(), EVP_PKEY_paramgen_init(), EVP_PKEY_keygen() و EVP_PKEY_paramgen() تُعيد 1 للنجاح و0 أو قيمة سالبة للفشل. على وجه الخصوص، قيمة الإرجاع -2 تشير إلى أن العملية غير مدعومة من خوارزمية المفتاح العام.

EVP_PKEY_Q_keygen() تُعيد EVP_PKEY، أو NULL عند الفشل.

ملاحظات¶

بعد استدعاء EVP_PKEY_keygen_init() أو EVP_PKEY_paramgen_init() يمكن تنفيذ عمليات تحكم خاصة بالخوارزمية لتعيين أي معاملات مناسبة للعملية.

يمكن استدعاء الدالتين EVP_PKEY_keygen() و EVP_PKEY_paramgen() أكثر من مرة على نفس السياق إذا نُفذت عدة عمليات باستخدام نفس المعاملات.

يعتمد معنى المعاملات الممررة إلى رد النداء على الخوارزمية والتنفيذ المحدد للخوارزمية. قد لا يعطي بعضها أي معلومات مفيدة على الإطلاق أثناء توليد المفتاح أو المعامل. وقد لا يستدعي البعض الآخر رد النداء حتى.

تعتمد العملية التي ينفذها توليد المفتاح أو المعامل على الخوارزمية المستخدمة. في بعض الحالات (مثل EC مع منحنى مسمى مزود) يحدد خيار "التوليد" الحقول المناسبة في بنية EVP_PKEY فقط.

في OpenSSL، تحتوي بنية EVP_PKEY التي تحتوي على مفتاح خاص أيضًا على مكونات المفتاح العام والمعاملات (إن وجدت). المفتاح الخاص في OpenSSL يعادل ما تسميه بعض المكتبات "زوج مفاتيح". يمكن استخدام المفتاح الخاص في دوال تتطلب استخدام مفتاح عام أو معاملات.

أمثلة¶

توليد مفتاح RSA بطول 2048 بت:

 #include <openssl/evp.h>
 #include <openssl/rsa.h>
 EVP_PKEY_CTX *ctx;
 EVP_PKEY *pkey = NULL;
 ctx = EVP_PKEY_CTX_new_id(EVP_PKEY_RSA, NULL);
 if (!ctx)
     /* Error occurred */
 if (EVP_PKEY_keygen_init(ctx) <= 0)
     /* Error */
 if (EVP_PKEY_CTX_set_rsa_keygen_bits(ctx, 2048) <= 0)
     /* Error */
 /* Generate key */
 if (EVP_PKEY_keygen(ctx, &pkey) <= 0)
     /* Error */

توليد مفتاح من مجموعة معاملات:

 #include <openssl/evp.h>
 #include <openssl/rsa.h>
 EVP_PKEY_CTX *ctx;
 ENGINE *eng;
 EVP_PKEY *pkey = NULL, *param;
 /* Assumed param, eng are set up already */
 ctx = EVP_PKEY_CTX_new(param, eng);
 if (!ctx)
     /* Error occurred */
 if (EVP_PKEY_keygen_init(ctx) <= 0)
     /* Error */
 /* Generate key */
 if (EVP_PKEY_keygen(ctx, &pkey) <= 0)
     /* Error */

مثال لرد نداء التوليد لتنفيذات المفتاح العام في OpenSSL:

 /* Application data is a BIO to output status to */
 EVP_PKEY_CTX_set_app_data(ctx, status_bio);
 static int genpkey_cb(EVP_PKEY_CTX *ctx)
 {
     char c = '*';
     BIO *b = EVP_PKEY_CTX_get_app_data(ctx);
     int p = EVP_PKEY_CTX_get_keygen_info(ctx, 0);
     if (p == 0)
         c = '.';
     if (p == 1)
         c = '+';
     if (p == 2)
         c = '*';
     if (p == 3)
         c = '\n';
     BIO_write(b, &c, 1);
     (void)BIO_flush(b);
     return 1;
 }

انظر أيضًا¶

EVP_RSA_gen(3), EVP_EC_gen(3), EVP_PKEY_CTX_new(3), EVP_PKEY_encrypt(3), EVP_PKEY_decrypt(3), EVP_PKEY_sign(3), EVP_PKEY_verify(3), EVP_PKEY_verify_recover(3), EVP_PKEY_derive(3)

التاريخ¶

EVP_PKEY_keygen_init(), int EVP_PKEY_paramgen_init(), EVP_PKEY_keygen(), EVP_PKEY_paramgen(), EVP_PKEY_gen_cb(), EVP_PKEY_CTX_set_cb(), EVP_PKEY_CTX_get_cb(), EVP_PKEY_CTX_get_keygen_info(), EVP_PKEY_CTX_set_app_data() و EVP_PKEY_CTX_get_app_data() أُضيفت في OpenSSL 1.0.0.

EVP_PKEY_Q_keygen() و EVP_PKEY_generate() أُضيفتا في OpenSSL 3.0.

حقوق النسخ¶

حقوق النشر 2006-2026 لمؤلفي مشروع OpenSSL. جميع الحقوق محفوظة.

مرخص بموجب رخصة Apache 2.0 (المشار إليها فيما يلي بـ ”الرخصة“). لا يجوز لك استخدام هذا الملف إلا وفقًا لشروط الرخصة. يمكنك الحصول على نسخة منها في الملف LICENSE الموجود في حزمة التوزيع المصدرية أو على الرابط <https://www.openssl.org/source/license.html>.

ترجمة¶

تُرجمت هذه الصفحة من الدليل بواسطة زايد السعيدي <zayed.alsaidi@gmail.com>

هذه الترجمة هي وثيقة مجانية؛ راجع رخصة جنو العامة الإصدار 3 أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات.

إذا وجدت أي أخطاء في ترجمة صفحة الدليل هذه، يرجى إرسال بريد إلكتروني إلى قائمة بريد المترجمين: kde-l10n-ar@kde.org.