الاسم¶

EVP_PKEY_set1_RSA, EVP_PKEY_set1_DSA, EVP_PKEY_set1_DH, EVP_PKEY_set1_EC_KEY, EVP_PKEY_get1_RSA, EVP_PKEY_get1_DSA, EVP_PKEY_get1_DH, EVP_PKEY_get1_EC_KEY, EVP_PKEY_get0_RSA, EVP_PKEY_get0_DSA, EVP_PKEY_get0_DH, EVP_PKEY_get0_EC_KEY, EVP_PKEY_assign_RSA, EVP_PKEY_assign_DSA, EVP_PKEY_assign_DH, EVP_PKEY_assign_EC_KEY, EVP_PKEY_assign_POLY1305, EVP_PKEY_assign_SIPHASH, EVP_PKEY_get0_hmac, EVP_PKEY_get0_poly1305, EVP_PKEY_get0_siphash, EVP_PKEY_get0, EVP_PKEY_type, EVP_PKEY_get_id, EVP_PKEY_get_base_id, EVP_PKEY_set1_engine, EVP_PKEY_get0_engine, EVP_PKEY_id, EVP_PKEY_base_id - دوال إسناد EVP_PKEY

موجز¶

 #include <openssl/evp.h>
 int EVP_PKEY_get_id(const EVP_PKEY *pkey);
 int EVP_PKEY_get_base_id(const EVP_PKEY *pkey);
 int EVP_PKEY_type(int type);
 #define EVP_PKEY_id EVP_PKEY_get_id
 #define EVP_PKEY_base_id EVP_PKEY_get_base_id

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

 int EVP_PKEY_set1_RSA(EVP_PKEY *pkey, RSA *key);
 int EVP_PKEY_set1_DSA(EVP_PKEY *pkey, DSA *key);
 int EVP_PKEY_set1_DH(EVP_PKEY *pkey, DH *key);
 int EVP_PKEY_set1_EC_KEY(EVP_PKEY *pkey, EC_KEY *key);
 RSA *EVP_PKEY_get1_RSA(EVP_PKEY *pkey);
 DSA *EVP_PKEY_get1_DSA(EVP_PKEY *pkey);
 DH *EVP_PKEY_get1_DH(EVP_PKEY *pkey);
 EC_KEY *EVP_PKEY_get1_EC_KEY(EVP_PKEY *pkey);
 const unsigned char *EVP_PKEY_get0_hmac(const EVP_PKEY *pkey, size_t *len);
 const unsigned char *EVP_PKEY_get0_poly1305(const EVP_PKEY *pkey, size_t *len);
 const unsigned char *EVP_PKEY_get0_siphash(const EVP_PKEY *pkey, size_t *len);
 const RSA *EVP_PKEY_get0_RSA(const EVP_PKEY *pkey);
 const DSA *EVP_PKEY_get0_DSA(const EVP_PKEY *pkey);
 const DH *EVP_PKEY_get0_DH(const EVP_PKEY *pkey);
 const EC_KEY *EVP_PKEY_get0_EC_KEY(const EVP_PKEY *pkey);
 void *EVP_PKEY_get0(const EVP_PKEY *pkey);
 int EVP_PKEY_assign_RSA(EVP_PKEY *pkey, RSA *key);
 int EVP_PKEY_assign_DSA(EVP_PKEY *pkey, DSA *key);
 int EVP_PKEY_assign_DH(EVP_PKEY *pkey, DH *key);
 int EVP_PKEY_assign_EC_KEY(EVP_PKEY *pkey, EC_KEY *key);
 int EVP_PKEY_assign_POLY1305(EVP_PKEY *pkey, ASN1_OCTET_STRING *key);
 int EVP_PKEY_assign_SIPHASH(EVP_PKEY *pkey, ASN1_OCTET_STRING *key);
 ENGINE *EVP_PKEY_get0_engine(const EVP_PKEY *pkey);
 int EVP_PKEY_set1_engine(EVP_PKEY *pkey, ENGINE *engine);

الوصف¶

EVP_PKEY_get_base_id() تُرجع نوع pkey. مثلاً، مفتاح RSA سيرجع EVP_PKEY_RSA.

تُعيد EVP_PKEY_get_id() NID الفعلي المرتبط بـ pkey فقط إذا لم يكن نوع pkey منفذًا فقط في provider(7). تاريخيًا، المفاتيح التي تستخدم نفس الخوارزمية يمكن أن تستخدم NIDs مختلفة. على سبيل المثال، مفتاح RSA يمكن أن يستخدم NIDs المقابلة لـ NIDs NID_rsaEncryption (ما يعادل EVP_PKEY_RSA) أو NID_rsa (ما يعادل EVP_PKEY_RSA2). استخدام NIDs البديلة غير القياسية أصبح نادرًا الآن لذا EVP_PKEY_RSA2 وغيرها لا تُرى كثيرًا عمليًا. تُعيد EVP_PKEY_get_id() -1 (EVP_PKEY_KEYMGMT) إذا كان pkey منفذًا فقط في provider(7).

EVP_PKEY_type() تُرجع النوع الأساسي لـ NID type. مثلاً، EVP_PKEY_type(EVP_PKEY_RSA2) سترجع EVP_PKEY_RSA.

EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() و EVP_PKEY_set1_EC_KEY() يضبطن المفتاح المُشار إليه بـ pkey إلى key. هذه الدوال مهملة. يجب على التطبيقات استخدام EVP_PKEY_fromdata(3) بدلاً منها.

EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH(), EVP_PKEY_assign_EC_KEY(), EVP_PKEY_assign_POLY1305() و EVP_PKEY_assign_SIPHASH() يضبطن المفتاح المُشار إليه إلى key لكنها تستخدم key المُقدم داخلياً، لذا سيُحرر key عندما يُحرر الأصل pkey. هذه الكليّات مهملة. يجب على التطبيقات بدلاً من ذلك قراءة EVP_PKEY مباشرة باستخدام واجهات برمجة OSSL_DECODER (انظر OSSL_DECODER_CTX_new_for_pkey(3))، أو بناء EVP_PKEY من بيانات باستخدام EVP_PKEY_fromdata(3).

EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() و EVP_PKEY_get1_EC_KEY() تُرجع المفتاح المُشار إليه في pkey أو NULL إذا لم يكن المفتاح من النوع الصحيح. يجب تحرير المفتاح المُرجَع بعد الاستخدام. هذه الدوال مهملة. يجب على التطبيقات استخدام EVP_PKEY مباشرة حيثما أمكن. إذا كان الوصول إلى معاملات المفتاح منخفضة المستوى مطلوباً، فيجب على التطبيقات استخدام EVP_PKEY_get_params(3) ودوال مشابهة أخرى. لكتابة EVP_PKEY، استخدم واجهات برمجة OSSL_ENCODER (انظر OSSL_ENCODER_CTX_new_for_pkey(3)).

EVP_PKEY_get0_hmac()، EVP_PKEY_get0_poly1305()، EVP_PKEY_get0_siphash()، EVP_PKEY_get0_RSA()، EVP_PKEY_get0_DSA()، EVP_PKEY_get0_DH() و EVP_PKEY_get0_EC_KEY() تُعيد المفتاح المُشار إليه في pkey أو NULL إذا لم يكن المفتاح من النوع الصحيح. عدد مراجع المفتاح المُعاد لا يُزاد، لذا لا يجب تحرير المفتاح بعد الاستخدام. هذه الدوال مُهملة. يجب على التطبيقات استخدام EVP_PKEY مباشرةً حيثما أمكن. إذا كان الوصول إلى معاملات المفتاح منخفضة المستوى مطلوبًا، فيجب على التطبيقات استخدام EVP_PKEY_get_params(3) ودوال أخرى مشابهة. لكتابة EVP_PKEY، استخدم واجهات برمجة OSSL_ENCODER (انظر OSSL_ENCODER_CTX_new_for_pkey(3)). EVP_PKEY_get0() تُعيد مؤشرًا إلى المفتاح القديم أو NULL إذا لم يكن المفتاح قديمًا.

لاحظ أنه إذا لم يُنشأ EVP_PKEY باستخدام إحدى الدوال المُهملة مثل EVP_PKEY_set1_RSA() أو EVP_PKEY_set1_DSA() أو EVP_PKEY_set1_DH() أو EVP_PKEY_set1_EC_KEY()، أو عبر وحدات الماكرو EVP_PKEY_assign المماثلة الموصوفة أعلاه، فإن المفتاح الداخلي سيُدار بواسطة مزود (انظر provider(7)). في تلك الحالة، المفتاح المُعاد بواسطة EVP_PKEY_get1_RSA() أو EVP_PKEY_get1_DSA() أو EVP_PKEY_get1_DH() أو EVP_PKEY_get1_EC_KEY() أو EVP_PKEY_get0_hmac() أو EVP_PKEY_get0_poly1305() أو EVP_PKEY_get0_siphash() أو EVP_PKEY_get0_RSA() أو EVP_PKEY_get0_DSA() أو EVP_PKEY_get0_DH() أو EVP_PKEY_get0_EC_KEY() سيكون نسخة مخبأة من مفتاح المزود. التحديثات اللاحقة لمفتاح المزود لن تنعكس مرة أخرى في النسخة المخبأة، والتحديثات التي يُجريها تطبيق على المفتاح المُعاد لن تنعكس مرة أخرى في مفتاح المزود. الاستدعاءات اللاحقة لـ EVP_PKEY_get1_RSA() أو EVP_PKEY_get1_DSA() أو EVP_PKEY_get1_DH() أو EVP_PKEY_get1_EC_KEY() ستُعيد دائمًا النسخة المخبأة التي أُعيدت بواسطة الاستدعاء الأول.

EVP_PKEY_get0_engine() تُعيد مرجعًا إلى ENGINE الذي يُعالج pkey. هذه الدالة مُهملة. يجب على التطبيقات استخدام المزوّدات بدلاً من المحركات (انظر provider(7) للتفاصيل).

EVP_PKEY_set1_engine() تُضبط ENGINE الذي يُعالج pkey إلى engine. يجب استدعاؤها بعد إعداد خوارزمية المفتاح ومكوناته. إذا لم يتضمن engine EVP_PKEY_METHOD لـ pkey، يحدث خطأ. هذه الدالة مُهملة. يجب على التطبيقات استخدام المزوّدات بدلاً من المحركات (انظر provider(7) للتفاصيل).

تحذيرات¶

الدوال التالية موثوقة فقط مع EVP_PKEY التي تم تعيين مفتاح داخلي لها باستخدام EVP_PKEY_assign_*():

EVP_PKEY_get_id()، EVP_PKEY_get_base_id()، EVP_PKEY_type()

لأغراض التحقق من نوع مفتاح EVP_PKEY، EVP_PKEY_is_a(3) أكثر عمومية.

لأغراض استرجاع اسم EVP_PKEY، الدالة EVP_PKEY_get0_type_name(3) أكثر فائدة بشكل عام.

المفاتيح المُعادة من الدوال EVP_PKEY_get0_RSA()، EVP_PKEY_get0_DSA()، EVP_PKEY_get0_DH() و EVP_PKEY_get0_EC_KEY() تم تغييرها ليكون لها نوع إرجاع "const" في OpenSSL 3.0. كما هو موصوف أعلاه، المفاتيح المُعادة قد تكون نسخًا مخبأة من المفتاح المحتفظ به في مزوّد. بسبب هذا، وعلى عكس الإصدارات السابقة من OpenSSL، يجب اعتبارها نسخًا للقراءة فقط من المفتاح. التحديثات على هذه المفاتيح لن تنعكس مرة أخرى على المفتاح في جانب المزوّد. الدوال EVP_PKEY_get1_RSA()، EVP_PKEY_get1_DSA()، EVP_PKEY_get1_DH() و EVP_PKEY_get1_EC_KEY() لم يتم تغييرها ليكون لها نوع إرجاع "const" لكي تتمكن التطبيقات من "تحرير" القيمة المُعادة. ومع ذلك، يجب على التطبيقات اعتبارها نسخًا للقراءة فقط.

ملاحظات¶

وفقًا لاتفاقية تسمية OpenSSL، يجب تحرير المفتاح الذي تم الحصول عليه من أو تعيينه إلى pkey باستخدام دوال 1 بالإضافة إلى pkey.

EVP_PKEY_assign_RSA() وEVP_PKEY_assign_DSA() وEVP_PKEY_assign_DH() وEVP_PKEY_assign_EC_KEY() وEVP_PKEY_assign_POLY1305() وEVP_PKEY_assign_SIPHASH() نُفذت كوحدات ماكرو.

تفحص EVP_PKEY_assign_EC_KEY() معرف اسم المنحنى لتحديد ما إذا كان EC_KEY المُمرر هو مفتاح SM2(7)، وستُعيِّن نوع EVP_PKEY إلى EVP_PKEY_SM2 في تلك الحالة، بدلاً من EVP_PKEY_EC.

معظم التطبيقات التي ترغب في معرفة نوع المفتاح ستستدعي ببساطة EVP_PKEY_get_base_id() ولن تهتم بالنوع الفعلي: والذي سيكون متطابقًا في جميع الحالات تقريبًا.

الإصدارات السابقة من هذا المستند اقترحت استخدام EVP_PKEY_type(pkey->type) لتحديد نوع المفتاح. نظرًا لأن EVP_PKEY أصبح الآن معتمًا، لم يعد هذا ممكنًا: المكافئ هو EVP_PKEY_get_base_id(pkey).

يُستخدم EVP_PKEY_set1_engine() عادةً بواسطة ENGINE يُعيد مفتاح HSM كجزء من روتينه لتحميل مفتاح خاص.

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

تُعيد EVP_PKEY_set1_RSA() وEVP_PKEY_set1_DSA() وEVP_PKEY_set1_DH() وEVP_PKEY_set1_EC_KEY() 1 للنجاح أو 0 للفشل.

تُعيد EVP_PKEY_get1_RSA() وEVP_PKEY_get1_DSA() وEVP_PKEY_get1_DH() وEVP_PKEY_get1_EC_KEY() المفتاح المُشار إليه أو NULL إذا حدث خطأ.

تُعيد EVP_PKEY_assign_RSA() وEVP_PKEY_assign_DSA() وEVP_PKEY_assign_DH() وEVP_PKEY_assign_EC_KEY() وEVP_PKEY_assign_POLY1305() وEVP_PKEY_assign_SIPHASH() 1 للنجاح و0 للفشل.

تُعيد EVP_PKEY_get_base_id() وEVP_PKEY_get_id() وEVP_PKEY_type() نوع مفتاح أو NID_undef (ما يعادل EVP_PKEY_NONE) عند الخطأ.

تُعيد EVP_PKEY_set1_engine() 1 للنجاح و0 للفشل.

انظر أيضًا¶

EVP_PKEY_new(3), SM2(7)

التاريخ¶

أُعيدت تسمية الدالتين EVP_PKEY_id() وEVP_PKEY_base_id() لتضمين "get" في أسمائهما في OpenSSL 3.0، على التوالي. الأسماء القديمة محفوظة كوحدات ماكرو بديلة غير مهملة.

أُهملت EVP_PKEY_set1_RSA وEVP_PKEY_set1_DSA وEVP_PKEY_set1_DH وEVP_PKEY_set1_EC_KEY وEVP_PKEY_get1_RSA وEVP_PKEY_get1_DSA وEVP_PKEY_get1_DH وEVP_PKEY_get1_EC_KEY وEVP_PKEY_get0_RSA وEVP_PKEY_get0_DSA وEVP_PKEY_get0_DH وEVP_PKEY_get0_EC_KEY وEVP_PKEY_assign_RSA وEVP_PKEY_assign_DSA وEVP_PKEY_assign_DH وEVP_PKEY_assign_EC_KEY وEVP_PKEY_assign_POLY1305 وEVP_PKEY_assign_SIPHASH وEVP_PKEY_get0_hmac وEVP_PKEY_get0_poly1305 وEVP_PKEY_get0_siphash وEVP_PKEY_set1_engine وEVP_PKEY_get0_engine في OpenSSL 3.0.

جُعلت القيمة المُعادة من EVP_PKEY_get0_RSA وEVP_PKEY_get0_DSA وEVP_PKEY_get0_DH وEVP_PKEY_get0_EC_KEY ثابتة (const) في OpenSSL 3.0.

الدالة EVP_PKEY_set_alias_type() كانت موثقة سابقًا في هذه الصفحة. أُزيلت في OpenSSL 3.0.

حقوق النسخ¶

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

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

ترجمة¶

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

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

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