EVP_DIGESTVERIFYINIT(3ssl)

الاسم
EVP_DigestVerifyInit_ex, EVP_DigestVerifyInit, EVP_DigestVerifyUpdate, EVP_DigestVerifyFinal, EVP_DigestVerify - دوال التحقق من التوقيع EVP

موجز
 #include <openssl/evp.h>

 int EVP_DigestVerifyInit_ex(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx,
                             const char *mdname, OSSL_LIB_CTX *libctx,
                             const char *props, EVP_PKEY *pkey,
                             const OSSL_PARAM params[]);
 int EVP_DigestVerifyInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx,
                          const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey);
 int EVP_DigestVerifyUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt);
 int EVP_DigestVerifyFinal(EVP_MD_CTX *ctx, const unsigned char *sig,
                           size_t siglen);
 int EVP_DigestVerify(EVP_MD_CTX *ctx, const unsigned char *sig,
                      size_t siglen, const unsigned char *tbs, size_t tbslen);

الوصف
إجراءات التوقيع EVP هي واجهة عالية المستوى للتوقيعات الرقمية. تُهضم بيانات الإدخال أولاً قبل أن يتم التحقق من التوقيع.

EVP_DigestVerifyInit_ex() تُعدّ سياق التحقق ctx لاستخدام هاضوم بالاسم mdname ومفتاح عام pkey. يُمرّر اسم الهاضوم المراد استخدامه إلى مزود خوارزمية التوقيع المستخدمة. كيفية تفسير المزود لاسم الهاضوم خاصة بالمزود. قد يُنفّذ المزود ذلك الهاضوم مباشرة بنفسه أو قد يختار (اختيارياً) جلبه (مما قد يؤدي إلى اختيار هاضوم من مزود مختلف). إذا دعم المزود جلب الهاضوم، فقد يستخدم وسيط props للخصائص التي ستُستخدم أثناء الجلب. أخيراً، تُضبط المعاملات الممررة params، إذا لم تكن NULL، على السياق قبل العودة.

تُستخدم خوارزمية pkey لجلب طريقة EVP_SIGNATURE ضمنيًا، لاستخدامها في التوقيع الفعلي. انظر "Implicit fetch" في provider(7) لمزيد من المعلومات حول عمليات الجلب الضمني.

تدعم مزودات OpenSSL المبدئية والقديمة جلب الخلاصات ويمكنها جلب هذه الخلاصات من أي مزود متاح. يدعم مزود OpenSSL FIPS أيضًا جلب الخلاصات ولكنه سيجلب فقط الخلاصات التي نُفذت هي نفسها داخل مزود FIPS.

يجب إنشاء ctx باستخدام EVP_MD_CTX_new() قبل استدعاء هذه الدالة. إذا لم يكن pctx NULL، فسيُكتب EVP_PKEY_CTX لعملية التحقق إلى *pctx: يمكن استخدام هذا لتعيين خيارات تحقق بديلة. لاحظ أن أي قيمة موجودة في *pctx تُستبدل. يجب ألا يُحرّر التطبيق قيمة EVP_PKEY_CTX المُعادة مباشرة إذا لم يُسند إلى ctx قيمة EVP_PKEY_CTX قبل تمريره إلى EVP_DigestVerifyInit_ex() (مما يعني أن EVP_PKEY_CTX يُنشأ داخل EVP_DigestVerifyInit_ex() وسيُحرّر آلياً عند تحرير EVP_MD_CTX). إذا كان EVP_PKEY_CTX المراد استخدامه منشأ بواسطة EVP_DigestVerifyInit_ex، فسيستخدم OSSL_LIB_CTX المحدد في libctx وسلسلة استعلام الخصائص المحددة في props.

لن يُنشأ EVP_PKEY_CTX بواسطة EVP_DigestVerifyInit_ex() إذا كان ctx الممرر قد أُسند إليه واحد بالفعل عبر EVP_MD_CTX_set_pkey_ctx(3). انظر أيضاً SM2(7).

لا يمكن استخدام جميع خلاصات الرسائل لجميع أنواع المفاتيح. تنطبق التوليفات التالية.

DSA يدعم SHA1 و SHA224 و SHA256 و SHA384 و SHA512

ECDSA
    يدعم SHA1 و SHA224 و SHA256 و SHA384 و SHA512 و SM3

RSA بدون حشوة
    لا يدعم أي هاضومات (يجب أن يكون الهاضوم type NULL)

RSA مع حشوة X931
    يدعم SHA1 و SHA256 و SHA384 و SHA512

جميع أنواع حشو RSA الأخرى
    دعم SHA1 و SHA224 و SHA256 و SHA384 و SHA512 و MD5 و MD5_SHA1 و MD2 و MD4 و MDC2 و SHA3-224 و SHA3-256 و SHA3-384 و SHA3-512

Ed25519 و Ed448
    لا تدعم أي هاضومات (يجب أن يكون الهاضوم type NULL)

HMAC
    يدعم أي خلاصة (digest)

CMAC وPoly1305 وSiphash
    سيتجاهل أي ملخص (digest) مقدم.

إذا استُخدم RSA-PSS وسرت قيود، فيجب أن يتطابق الملخص.

تعمل EVP_DigestVerifyInit() بنفس طريقة EVP_DigestVerifyInit_ex() باستثناء أن معامل mdname سيُستنتج من الهاضوم المقدم type، وستكون props NULL. حيثما يُقدم، سيُستخدم ENGINE e لتنفيذ التحقق من التوقيع وخوارزمية الهاضوم. قد يكون e NULL.

تُجزئ EVP_DigestVerifyUpdate() cnt بايت من البيانات عند d في سياق التحقق ctx. يمكن استدعاء هذه الدالة عدة مرات على نفس ctx لتضمين بيانات إضافية.

تتحقق EVP_DigestVerifyFinal() من البيانات في ctx مقابل التوقيع في sig بطول siglen.

تتحقق EVP_DigestVerify() من tbslen بايت عند tbs مقابل التوقيع في sig بطول siglen.

القيم المُرجعة
تُرجع EVP_DigestVerifyInit() وEVP_DigestVerifyUpdate() 1 للنجاح و0 للفشل.

تُرجع EVP_DigestVerifyFinal() وEVP_DigestVerify() 1 للنجاح؛ أي قيمة أخرى تشير إلى الفشل. تشير قيمة الإرجاع صفر إلى أن التوقيع لم يُتحقق بنجاح (أي أن tbs لم يطابق البيانات الأصلية أو أن التوقيع كان بصيغة غير صالحة)، بينما تشير القيم الأخرى إلى خطأ أكثر خطورة (وتشير أحياناً أيضاً إلى صيغة توقيع غير صالحة).

يمكن الحصول على رموز الخطأ من ERR_get_error(3).

ملاحظات
ينبغي دائمًا استخدام واجهة EVP للتواقيع الرقمية بدلاً من الواجهات منخفضة المستوى. هذا لأن الكود يصبح حينها شفافًا للخوارزمية المستخدمة وأكثر مرونة بكثير.

EVP_DigestVerify() هي عملية لمرة واحدة تتحقق من كتلة واحدة من البيانات في دالة واحدة. بالنسبة للخوارزميات التي تدعم التدفق، فهي مكافئة لاستدعاء EVP_DigestVerifyUpdate() وEVP_DigestVerifyFinal(). بالنسبة للخوارزميات التي لا تدعم التدفق (مثل PureEdDSA)، فهي الطريقة الوحيدة للتحقق من البيانات.

في الإصدارات السابقة من OpenSSL، كان هناك ارتباط بين أنواع ملخصات الرسائل (message digest) وخوارزميات المفتاح العام. وهذا يعني أن ملخصات "الاستنساخ" مثل EVP_dss1() كانت مطلوبة للتوقيع باستخدام SHA1 و DSA. لم يعد هذا ضرورياً ويُنصح الآن بعدم استخدام ملخصات الاستنساخ.

لبعض أنواع المفاتيح والمعلمات، يجب بذر مولد الأرقام العشوائية. إذا فشل البذر الآلي أو إعادة البذر لـ OpenSSL CSPRNG بسبب ظروف خارجية (راجع RAND(7))، فستفشل العملية.

استدعاء EVP_DigestVerifyFinal() يُنهي داخلياً نسخة من سياق الهاضوم. هذا يعني أنه يمكن استدعاء EVP_VerifyUpdate() وEVP_VerifyFinal() لاحقاً لهضم والتحقق من بيانات إضافية. قد تُعطّل التطبيقات هذا السلوك بتعيين علم سياق EVP_MD_CTX_FLAG_FINALISE عبر EVP_MD_CTX_set_flags(3).

لاحظ أنه لا تدعم جميع المزودين الاستمرارية، في حال عدم السماح للمزود المختار بتكرار السياقات، فسوف يُنهي EVP_DigestVerifyFinal() سياق الهاضوم وستؤدي محاولة معالجة بيانات إضافية عبر EVP_DigestVerifyUpdate() إلى خطأ.

يمكن استدعاء الدالتين EVP_DigestVerifyInit() و EVP_DigestVerifyInit_ex() مرات متعددة على سياق، ويجب حفظ المعاملات المحددة بواسطة الاستدعاءات السابقة إذا كان معامل pkey هو NULL. عندئذ يُعيد الاستدعاء فقط ضبط حالة ctx.

يمكن استدعاء EVP_DigestVerify() مرة واحدة فقط، ولا يمكن استخدامها مرة أخرى دون إعادة تهيئة EVP_MD_CTX باستدعاء EVP_DigestVerifyInit_ex().

قد يؤدي تجاهل إرجاعات الفشل للدالتين EVP_DigestVerifyInit() و EVP_DigestVerifyInit_ex() إلى سلوك غير محدد لاحق عند استدعاء EVP_DigestVerifyUpdate() أو EVP_DigestVerifyFinal() أو EVP_DigestVerify().

انظر أيضًا
EVP_DigestSignInit(3), EVP_DigestInit(3), evp(7), HMAC(3), MD2(3), MD5(3), MDC2(3), RIPEMD160(3), SHA1(3), openssl-dgst(1), RAND(7)

التاريخ
أُضيفت EVP_DigestVerifyInit() و EVP_DigestVerifyUpdate() و EVP_DigestVerifyFinal() في OpenSSL 1.0.0.

أُضيفت EVP_DigestVerifyInit_ex() في OpenSSL 3.0.

حُوّلت EVP_DigestVerifyUpdate() من ماكرو إلى دالة في OpenSSL 3.0.

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

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

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

هذه الترجمة هي وثيقة مجانية؛ راجع رخصة جنو العامة الإصدار 3 (https://www.gnu.org/licenses/gpl-3.0.html) أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات.

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