الاسم¶

EVP_PKEY, EVP_PKEY_new, EVP_PKEY_up_ref, EVP_PKEY_dup, EVP_PKEY_free, EVP_PKEY_new_raw_private_key_ex, EVP_PKEY_new_raw_private_key, EVP_PKEY_new_raw_public_key_ex, EVP_PKEY_new_raw_public_key, EVP_PKEY_new_CMAC_key, EVP_PKEY_new_mac_key, EVP_PKEY_get_raw_private_key, EVP_PKEY_get_raw_public_key \&- دوال تخصيص المفتاح العام/الخاص ومعالجة المفتاح الخام

موجز¶

 #include <openssl/evp.h>
 typedef evp_pkey_st EVP_PKEY;
 EVP_PKEY *EVP_PKEY_new(void);
 int EVP_PKEY_up_ref(EVP_PKEY *key);
 EVP_PKEY *EVP_PKEY_dup(EVP_PKEY *key);
 void EVP_PKEY_free(EVP_PKEY *key);
 EVP_PKEY *EVP_PKEY_new_raw_private_key_ex(OSSL_LIB_CTX *libctx,
                                           const char *keytype,
                                           const char *propq,
                                           const unsigned char *key,
                                           size_t keylen);
 EVP_PKEY *EVP_PKEY_new_raw_private_key(int type, ENGINE *e,
                                        const unsigned char *key, size_t keylen);
 EVP_PKEY *EVP_PKEY_new_raw_public_key_ex(OSSL_LIB_CTX *libctx,
                                          const char *keytype,
                                          const char *propq,
                                          const unsigned char *key,
                                          size_t keylen);
 EVP_PKEY *EVP_PKEY_new_raw_public_key(int type, ENGINE *e,
                                       const unsigned char *key, size_t keylen);
 EVP_PKEY *EVP_PKEY_new_mac_key(int type, ENGINE *e, const unsigned char *key,
                                int keylen);
 int EVP_PKEY_get_raw_private_key(const EVP_PKEY *pkey, unsigned char *priv,
                                  size_t *len);
 int EVP_PKEY_get_raw_public_key(const EVP_PKEY *pkey, unsigned char *pub,
                                 size_t *len);

الدالة التالية أصبحت مهجورة منذ OpenSSL 3.0، ويمكن إخفاؤها تمامًا عبر تعريف OPENSSL_API_COMPAT بقيمة إصدار مناسبة، انظر openssl_user_macros(7):

 EVP_PKEY *EVP_PKEY_new_CMAC_key(ENGINE *e, const unsigned char *priv,
                                 size_t len, const EVP_CIPHER *cipher);

الوصف¶

EVP_PKEY هو هيكل عام لحمل أنواع متنوعة من المفاتيح غير المتماثلة (المعروفة أيضًا باسم "أزواج المفاتيح")، ويمكن استخدامه لعمليات متنوعة، مثل التوقيع، التحقق من التوقيعات، اشتقاق المفاتيح، إلخ. المفاتيح غير المتماثلة نفسها يُشار إليها غالبًا باسم "المفتاح الداخلي"، وتُعالج بواسطة الواجهات الخلفية، مثل المزودين (عبر EVP_KEYMGMT(3)) أو ENGINE.

مفاهيميًا، قد يحمل المفتاح الداخلي لـ EVP_PKEY مفتاحًا خاصًا، أو مفتاحًا عامًا، أو كليهما (زوج مفاتيح)، وإلى جانب ذلك، معاملات المفتاح إذا كان نوع المفتاح يتطلبها. وجود هذه المكونات يُحدد العمليات التي يمكن إجراؤها؛ على سبيل المثال، يتطلب التوقيع عادةً وجود مفتاح خاص، ويتطلب التحقق عادةً وجود مفتاح عام.

EVP_PKEY استُخدم أيضًا لخوارزميات MAC التي صُممت لإنتاج توقيعات، على الرغم من أنها ليست خوارزميات مفاتيح عامة؛ "POLY1305"، "SIPHASH"، "HMAC"، "CMAC". يُعتبر هذا الاستخدام قديمًا ويُثبط لصالح واجهة برمجة التطبيقات EVP_MAC(3).

الدالة EVP_PKEY_new() تُخصص هيكل EVP_PKEY فارغ يُستخدم بواسطة OpenSSL لتخزين المفاتيح العامة والخاصة. يُضبط عدد المراجع إلى 1.

EVP_PKEY_up_ref() تزيد عدد المراجع لـ key.

EVP_PKEY_dup() تُكرر key. يجب ألا يكون key قائمًا على ENGINE أو مفتاحًا خامًا، وإلا فشلت عملية التكرار.

EVP_PKEY_free() تُنقص عدد المراجع لـ key، وإذا كان عدد المراجع صفرًا، تُحرره. إذا كان key هو NULL، لا يُفعل شيء.

EVP_PKEY_new_raw_private_key_ex() تُخصص EVP_PKEY جديد. ما لم يُستخدم محرك لنوع المفتاح، يُوجد مزود للمفتاح باستخدام سياق المكتبة libctx وسلسلة استعلام الخاصية propq. تشير الوسيطة keytype إلى نوع هذا المفتاح. يجب أن تكون القيمة سلسلة محارف لخوارزمية مفتاح عام تدعم المفاتيح الخاصة الخام، على سبيل المثال، واحدة من: "ED25519", "ED448", "X25519", "X448", "ML-DSA-44", "ML-DSA-65", "ML-DSA-87", "ML-KEM-512", "ML-KEM-768", أو "ML-KEM-1024". يشير key إلى بيانات المفتاح الخاص الخام لـ EVP_PKEY هذا والتي يجب أن تكون بطول keylen. يجب أن يكون الطول مناسبًا لنوع المفتاح. تُشتق بيانات المفتاح العام آليًا من بيانات المفتاح الخاص المُعطاة (إذا كان ذلك مناسبًا لنوع الخوارزمية).

EVP_PKEY_new_raw_private_key() تفعل نفس ما تفعله EVP_PKEY_new_raw_private_key_ex() باستثناء استخدام سياق المكتبة المبدئي واستعلام الخاصية المبدئي بدلاً من ذلك. إذا كان e غير NULL، يُربط هيكل EVP_PKEY الجديد بالمحرك e. تشير الوسيطة type إلى نوع هذا المفتاح. يجب أن تكون القيمة NID لخوارزمية مفتاح عام تدعم المفاتيح الخاصة الخام، أي واحدة من EVP_PKEY_X25519، EVP_PKEY_ED25519، EVP_PKEY_X448 أو EVP_PKEY_ED448.

EVP_PKEY_new_raw_private_key_ex() و EVP_PKEY_new_raw_private_key() قد تُستخدمان أيضًا مع معظم MACs المُنفذة كخوارزميات مفاتيح عامة، لذا تُقبل أنواع المفاتيح مثل "HMAC"، "POLY1305"، "SIPHASH"، أو شكلها NID EVP_PKEY_POLY1305، EVP_PKEY_SIPHASH، EVP_PKEY_HMAC. هذا الاستخدام، كما ذُكر أعلاه، يُثبط لصالح واجهة برمجة التطبيقات EVP_MAC(3).

EVP_PKEY_new_raw_public_key_ex() تعمل بنفس طريقة EVP_PKEY_new_raw_private_key_ex() باستثناء أن key يشير إلى بيانات المفتاح العام الخام. يُهيأ هيكل EVP_PKEY دون أي معلومات مفتاح خاص. أنواع الخوارزميات التي تدعم المفاتيح العامة الخام هي ED25519، ED448، X25519، X448، "ML-DSA-44", "ML-DSA-65", "ML-DSA-87", ML-KEM-512، ML-KEM-768، و ML-KEM-1024.

EVP_PKEY_new_raw_public_key() تعمل بنفس طريقة EVP_PKEY_new_raw_private_key_ex() باستثناء أن key يشير إلى بيانات المفتاح العام الخام. يُهيأ هيكل EVP_PKEY دون أي معلومات مفتاح خاص.

تعمل الدالة EVP_PKEY_new_mac_key() بنفس طريقة عمل EVP_PKEY_new_raw_private_key(). يجب على التطبيقات الجديدة استخدام EVP_PKEY_new_raw_private_key() بدلاً منها.

EVP_PKEY_get_raw_private_key() تملأ المخزن المؤقت المقدم بواسطة priv ببيانات المفتاح الخاص الخام. يجب أن يكون حجم المخزن المؤقت priv في *len عند الدخول إلى الدالة، وعند الخروج يُحدّث *len بعدد البايتات المكتوبة فعليًا. إذا كان المخزن المؤقت priv هو NULL، فسيُملأ *len بعدد البايتات المطلوبة لحمل المفتاح. التطبيق المُستدعي مسؤول عن ضمان أن المخزن المؤقت كبير بما يكفي لاستقبال بيانات المفتاح الخاص. تعمل هذه الدالة فقط مع الخوارزميات التي تدعم المفاتيح الخاصة الخام. تشمل هذه: ED25519، ED448، X25519، X448، HMAC، POLY1305، و SIPHASH. EVP_PKEY_get_raw_private_key() تعمل أيضًا مع مفاتيح "ML-DSA-44"، "ML-DSA-65"، "ML-DSA-87"، ML-KEM-512، ML-KEM-768 و ML-KEM-1024، والتي ليس لها تعيينات رقمية قديمة NID، لكن شكلها الخام متاح مع ذلك.

EVP_PKEY_get_raw_public_key() تملأ المخزن المؤقت المقدم بواسطة pub ببيانات المفتاح العام الخام. يجب أن يكون حجم المخزن المؤقت pub في *len عند الدخول إلى الدالة، وعند الخروج يُحدّث *len بعدد البايتات المكتوبة فعليًا. إذا كان المخزن المؤقت pub هو NULL، فسيُملأ *len بعدد البايتات المطلوبة لحمل المفتاح. التطبيق المُستدعي مسؤول عن ضمان أن المخزن المؤقت كبير بما يكفي لاستقبال بيانات المفتاح العام. تعمل هذه الدالة فقط مع الخوارزميات التي تدعم المفاتيح العامة الخام. تشمل هذه: ED25519، ED448، X25519، و X448 EVP_PKEY_get_raw_public_key() تعمل أيضًا مع مفاتيح "ML-DSA-44"، "ML-DSA-65"، "ML-DSA-87"، ML-KEM-512، ML-KEM-768 و ML-KEM-1024، والتي ليس لها تعيينات رقمية قديمة NID، لكن شكلها الخام متاح مع ذلك.

EVP_PKEY_new_CMAC_key() تعمل بنفس طريقة EVP_PKEY_new_raw_private_key() باستثناء أنها مخصصة فقط لنوع الخوارزمية EVP_PKEY_CMAC. بالإضافة إلى بيانات المفتاح الخاص الخام، تأخذ أيضًا خوارزمية تعمية لاستخدامها أثناء إنشاء CMAC في وسيط cipher. يجب أن يكون المُعمِّي مُعمِّي تشفير قياسيًا فقط. على سبيل المثال، لا ينبغي استخدام معميات AEAD و XTS.

يجب على التطبيقات استخدام واجهة برمجة التطبيقات EVP_MAC(3) بدلاً من ذلك وتعيين المعامل OSSL_MAC_PARAM_CIPHER على كائن EVP_MAC_CTX باسم المُعمِّي المستخدم.

ملاحظات¶

يُستخدم هيكل EVP_PKEY بواسطة دوال OpenSSL المتنوعة التي تتطلب مفتاحًا خاصًا عامًا دون الإشارة إلى أي خوارزمية معينة.

الهيكل الذي تُرجعه EVP_PKEY_new() فارغ. لإضافة مفتاح خاص أو عام إلى هذا الهيكل الفارغ، استخدم الدوال المناسبة الموصوفة في EVP_PKEY_set1_RSA(3)، EVP_PKEY_set1_DSA(3)، EVP_PKEY_set1_DH(3) أو EVP_PKEY_set1_EC_KEY(3) لأنواع المفاتيح القديمة المنفذة في موفري OpenSSL الداخليين.

لأنواع المفاتيح المُدارة بالكامل بواسطة الموفّر (انظر provider-keymgmt(7))، والتي قد تُنفذ في موفّرين خارجيين، استخدم دوالًا مثل EVP_PKEY_set1_encoded_public_key(3) أو EVP_PKEY_fromdata(3) لملء بيانات المفتاح.

بشكل عام، يُنصح بالحذر عند استخدام هيكل EVP_PKEY عبر سياقات مكتبة مختلفة: لكي يُشارك EVP_PKEY بواسطة سياقات مكتبة متعددة، يجب أن يكون لدى الموفّرين المرتبطين بسياقات المكتبة مديرو مفاتيح يدعمون نوع المفتاح وينفذون الدوال OSSL_FUNC_keymgmt_import() و OSSL_FUNC_keymgmt_export().

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

EVP_PKEY_new()، EVP_PKEY_new_raw_private_key()، EVP_PKEY_new_raw_public_key()، EVP_PKEY_new_CMAC_key() و EVP_PKEY_new_mac_key() تُرجع إما هيكل EVP_PKEY المُخصص حديثًا أو NULL إذا حدث خطأ.

EVP_PKEY_dup() تُرجع نسخة المفتاح المكررة أو NULL إذا حدث خطأ.

EVP_PKEY_up_ref()، EVP_PKEY_get_raw_private_key() و EVP_PKEY_get_raw_public_key() تُرجع 1 للنجاح و 0 للفشل.

انظر أيضًا¶

EVP_PKEY_set1_RSA(3)، EVP_PKEY_set1_DSA(3)، EVP_PKEY_set1_DH(3)، EVP_PKEY_set1_EC_KEY(3)، EVP_PKEY-ED25519(7)، EVP_PKEY-ED448(7). EVP_PKEY-HMAC(7)، EVP_PKEY-Poly1305(7)، EVP_PKEY-Siphash(7)، EVP_PKEY-X25519(7)، EVP_PKEY-X448(7)، EVP_PKEY-ML-DSA(7)، EVP_PKEY-ML-KEM(7).

التاريخ¶

توجد الدالتان EVP_PKEY_new() و EVP_PKEY_free() في جميع إصدارات OpenSSL.

أُضيفت الدالة EVP_PKEY_up_ref() في OpenSSL 1.1.0.

أُضيفت الدوال EVP_PKEY_new_raw_private_key()، EVP_PKEY_new_raw_public_key()، EVP_PKEY_new_CMAC_key()، EVP_PKEY_new_raw_private_key() و EVP_PKEY_get_raw_public_key() في OpenSSL 1.1.1.

أُضيفت الدوال EVP_PKEY_dup()، EVP_PKEY_new_raw_private_key_ex()، و EVP_PKEY_new_raw_public_key_ex() في OpenSSL 3.0.

أُهملت EVP_PKEY_new_CMAC_key() في OpenSSL 3.0.

عُدلت وثائق EVP_PKEY في OpenSSL 3.0 للسماح بوجود الجزء الخاص من زوج المفاتيح دون الجزء العام، حيث كان هذا مُضمنًا سابقًا على أنه غير مسموح به.

أُضيف دعم لـ ML-DSA و ML-KEM في الإصدار 3.5 من OpenSSL.

حقوق النسخ¶

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

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

ترجمة¶

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

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

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