Scroll to navigation

EVP_DIGESTINIT(3SSL) OpenSSL EVP_DIGESTINIT(3SSL)

الاسم

EVP_MD_fetch, EVP_MD_up_ref, EVP_MD_free, EVP_MD_get_params, EVP_MD_gettable_params, EVP_MD_CTX_new, EVP_MD_CTX_reset, EVP_MD_CTX_free, EVP_MD_CTX_dup, EVP_MD_CTX_copy, EVP_MD_CTX_copy_ex, EVP_MD_CTX_ctrl, EVP_MD_CTX_set_params, EVP_MD_CTX_get_params, EVP_MD_settable_ctx_params, EVP_MD_gettable_ctx_params, EVP_MD_CTX_settable_params, EVP_MD_CTX_gettable_params, EVP_MD_CTX_set_flags, EVP_MD_CTX_clear_flags, EVP_MD_CTX_test_flags, EVP_Q_digest, EVP_Digest, EVP_DigestInit_ex2, EVP_DigestInit_ex, EVP_DigestInit, EVP_DigestUpdate, EVP_DigestFinal_ex, EVP_DigestFinalXOF, EVP_DigestFinal, EVP_DigestSqueeze, EVP_MD_is_a, EVP_MD_get0_name, EVP_MD_get0_description, EVP_MD_names_do_all, EVP_MD_get0_provider, EVP_MD_get_type, EVP_MD_get_pkey_type, EVP_MD_get_size, EVP_MD_get_block_size, EVP_MD_get_flags, EVP_MD_CTX_get0_name, EVP_MD_CTX_md, EVP_MD_CTX_get0_md, EVP_MD_CTX_get1_md, EVP_MD_CTX_get_type, EVP_MD_CTX_get_size_ex, EVP_MD_CTX_get_block_size, EVP_MD_CTX_get0_md_data, EVP_MD_CTX_update_fn, EVP_MD_CTX_set_update_fn, EVP_md_null, EVP_get_digestbyname, EVP_get_digestbynid, EVP_get_digestbyobj, EVP_MD_CTX_get_pkey_ctx, EVP_MD_CTX_set_pkey_ctx, EVP_MD_do_all_provided, EVP_MD_type, EVP_MD_nid, EVP_MD_name, EVP_MD_pkey_type, EVP_MD_size, EVP_MD_block_size, EVP_MD_flags, EVP_MD_xof, EVP_MD_CTX_size, EVP_MD_CTX_get_size, EVP_MD_CTX_block_size, EVP_MD_CTX_type, EVP_MD_CTX_pkey_ctx, EVP_MD_CTX_md_data - إجراءات التلخيص EVP

موجز

 #include <openssl/evp.h>
 EVP_MD *EVP_MD_fetch(OSSL_LIB_CTX *ctx, const char *algorithm,
                      const char *properties);
 int EVP_MD_up_ref(EVP_MD *md);
 void EVP_MD_free(EVP_MD *md);
 int EVP_MD_get_params(const EVP_MD *digest, OSSL_PARAM params[]);
 const OSSL_PARAM *EVP_MD_gettable_params(const EVP_MD *digest);
 EVP_MD_CTX *EVP_MD_CTX_new(void);
 int EVP_MD_CTX_reset(EVP_MD_CTX *ctx);
 void EVP_MD_CTX_free(EVP_MD_CTX *ctx);
 void EVP_MD_CTX_ctrl(EVP_MD_CTX *ctx, int cmd, int p1, void* p2);
 int EVP_MD_CTX_get_params(EVP_MD_CTX *ctx, OSSL_PARAM params[]);
 int EVP_MD_CTX_set_params(EVP_MD_CTX *ctx, const OSSL_PARAM params[]);
 const OSSL_PARAM *EVP_MD_settable_ctx_params(const EVP_MD *md);
 const OSSL_PARAM *EVP_MD_gettable_ctx_params(const EVP_MD *md);
 const OSSL_PARAM *EVP_MD_CTX_settable_params(EVP_MD_CTX *ctx);
 const OSSL_PARAM *EVP_MD_CTX_gettable_params(EVP_MD_CTX *ctx);
 void EVP_MD_CTX_set_flags(EVP_MD_CTX *ctx, int flags);
 void EVP_MD_CTX_clear_flags(EVP_MD_CTX *ctx, int flags);
 int EVP_MD_CTX_test_flags(const EVP_MD_CTX *ctx, int flags);
 int EVP_Q_digest(OSSL_LIB_CTX *libctx, const char *name, const char *propq,
                  const void *data, size_t datalen,
                  unsigned char *md, size_t *mdlen);
 int EVP_Digest(const void *data, size_t count, unsigned char *md,
                unsigned int *size, const EVP_MD *type, ENGINE *impl);
 int EVP_DigestInit_ex2(EVP_MD_CTX *ctx, const EVP_MD *type,
                        const OSSL_PARAM params[]);
 int EVP_DigestInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl);
 int EVP_DigestUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt);
 int EVP_DigestFinal_ex(EVP_MD_CTX *ctx, unsigned char *md, unsigned int *s);
 int EVP_DigestFinalXOF(EVP_MD_CTX *ctx, unsigned char *out, size_t outlen);
 int EVP_DigestSqueeze(EVP_MD_CTX *ctx, unsigned char *out, size_t outlen);
 EVP_MD_CTX *EVP_MD_CTX_dup(const EVP_MD_CTX *in);
 int EVP_MD_CTX_copy_ex(EVP_MD_CTX *out, const EVP_MD_CTX *in);
 int EVP_DigestInit(EVP_MD_CTX *ctx, const EVP_MD *type);
 int EVP_DigestFinal(EVP_MD_CTX *ctx, unsigned char *md, unsigned int *s);
 int EVP_MD_CTX_copy(EVP_MD_CTX *out, EVP_MD_CTX *in);
 const char *EVP_MD_get0_name(const EVP_MD *md);
 const char *EVP_MD_get0_description(const EVP_MD *md);
 int EVP_MD_is_a(const EVP_MD *md, const char *name);
 int EVP_MD_names_do_all(const EVP_MD *md,
                         void (*fn)(const char *name, void *data),
                         void *data);
 const OSSL_PROVIDER *EVP_MD_get0_provider(const EVP_MD *md);
 int EVP_MD_get_type(const EVP_MD *md);
 int EVP_MD_get_pkey_type(const EVP_MD *md);
 int EVP_MD_get_size(const EVP_MD *md);
 int EVP_MD_get_block_size(const EVP_MD *md);
 unsigned long EVP_MD_get_flags(const EVP_MD *md);
 int EVP_MD_xof(const EVP_MD *md);
 const EVP_MD *EVP_MD_CTX_get0_md(const EVP_MD_CTX *ctx);
 EVP_MD *EVP_MD_CTX_get1_md(EVP_MD_CTX *ctx);
 const char *EVP_MD_CTX_get0_name(const EVP_MD_CTX *ctx);
 int EVP_MD_CTX_get_size_ex(const EVP_MD_CTX *ctx);
 int EVP_MD_CTX_get_block_size(const EVP_MD_CTX *ctx);
 int EVP_MD_CTX_get_type(const EVP_MD_CTX *ctx);
 void *EVP_MD_CTX_get0_md_data(const EVP_MD_CTX *ctx);
 const EVP_MD *EVP_md_null(void);
 const EVP_MD *EVP_get_digestbyname(const char *name);
 const EVP_MD *EVP_get_digestbynid(int type);
 const EVP_MD *EVP_get_digestbyobj(const ASN1_OBJECT *o);
 EVP_PKEY_CTX *EVP_MD_CTX_get_pkey_ctx(const EVP_MD_CTX *ctx);
 void EVP_MD_CTX_set_pkey_ctx(EVP_MD_CTX *ctx, EVP_PKEY_CTX *pctx);
 void EVP_MD_do_all_provided(OSSL_LIB_CTX *libctx,
                             void (*fn)(EVP_MD *mac, void *arg),
                             void *arg);
 #define EVP_MD_type EVP_MD_get_type
 #define EVP_MD_nid EVP_MD_get_type
 #define EVP_MD_name EVP_MD_get0_name
 #define EVP_MD_pkey_type EVP_MD_get_pkey_type
 #define EVP_MD_size EVP_MD_get_size
 #define EVP_MD_block_size EVP_MD_get_block_size
 #define EVP_MD_flags EVP_MD_get_flags
 #define EVP_MD_CTX_get_size EVP_MD_CTX_get_size_ex
 #define EVP_MD_CTX_size EVP_MD_CTX_get_size_ex
 #define EVP_MD_CTX_block_size EVP_MD_CTX_get_block_size
 #define EVP_MD_CTX_type EVP_MD_CTX_get_type
 #define EVP_MD_CTX_pkey_ctx EVP_MD_CTX_get_pkey_ctx
 #define EVP_MD_CTX_md_data EVP_MD_CTX_get0_md_data

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

 const EVP_MD *EVP_MD_CTX_md(const EVP_MD_CTX *ctx);
 int (*EVP_MD_CTX_update_fn(EVP_MD_CTX *ctx))(EVP_MD_CTX *ctx,
                                              const void *data, size_t count);
 void EVP_MD_CTX_set_update_fn(EVP_MD_CTX *ctx,
                               int (*update)(EVP_MD_CTX *ctx,
                                             const void *data, size_t count));

الوصف

إجراءات التلخيص EVP هي واجهة عالية المستوى لتلخيصات الرسائل ودوال الإخراج القابلة للتمديد (XOF).

النوع EVP_MD هو بنية لتنفيذ طريقة التلخيص.

كل خوارزمية تلخيص رسالة (مثل SHA256) تُنتج طول إخراج ثابت الحجم يُعاد عند استدعاء EVP_DigestFinal_ex(). دوال الإخراج القابلة للتمديد (XOF) مثل SHAKE256 لها طول إخراج متغير الحجم outlen يمكن استخدامه إما مع EVP_DigestFinalXOF() أو EVP_DigestSqueeze(). يمكن أيضًا استخدام EVP_DigestFinal_ex() مع XOF، لكن يجب تعيين "xoflen" مسبقًا (انظر "المعاملات"). لاحظ أن EVP_MD_get_size() و EVP_MD_CTX_get_size_ex() يتصرفان بشكل مختلف مع XOF.

يجلب تنفيذ التلخيص للخوارزمية algorithm المعطاة من أي مزود يقدمها، ضمن المعايير المحددة بواسطة properties. انظر "جلب الخوارزميات" في crypto(7) لمزيد من المعلومات.

يجب تحرير القيمة المُعادة في النهاية باستخدام EVP_MD_free().

بنى EVP_MD المجلوبة تُحسب بالمراجع.

يزيد عدد المراجع لبنية EVP_MD.
يخفض عدد المراجع لبنية EVP_MD المجلوبة. إذا انخفض عدد المراجع إلى 0، تُحرر البنية. إذا كانت الوسيطة NULL، لا يُفعل شيء.
تُخصِّص وتُعيد سياق تلخيص.
تُعيد ضبط سياق التلخيص ctx. يُمكن استخدام هذا لإعادة استخدام سياق موجود مسبقًا.
تُنظِّف سياق التلخيص ctx وتُحرِّر المساحة المُخصَّصة له. إذا كانت الوسيطة NULL، لا يُفعل شيء.
هذه طريقة قديمة. EVP_MD_CTX_set_params() و EVP_MD_CTX_get_params() هما الآلية التي ينبغي استخدامها لتعيين وجلب المعاملات التي يستخدمها المزوّدون.

تُنفِّذ إجراءات تحكم خاصة بالتلخيص على السياق ctx. يُشار إلى أمر التحكم في cmd وأي وسائط إضافية في p1 و p2. يجب استدعاء EVP_MD_CTX_ctrl() بعد EVP_DigestInit_ex2(). قد تنطبق قيود أخرى اعتمادًا على نوع التحكم وتنفيذ التلخيص.

إذا استُخدمت هذه الدالة مع EVP_MD مُسترجَع، فستترجم عناصر التحكم المعروفة لـ OpenSSL إلى معاملات OSSL_PARAM(3) بمفاتيح مُعرَّفة من OpenSSL وتستدعي EVP_MD_CTX_get_params() أو EVP_MD_CTX_set_params() حسب ما يناسب كل أمر تحكم.

انظر "CONTROLS" أدناه لمزيد من المعلومات، بما في ذلك الترجمات التي تُجرى.

تسترد القائمة المطلوبة من params من MD md. انظر "المعاملات" أدناه لمزيد من المعلومات.
تسترد القائمة المطلوبة من params من سياق MD ctx. انظر "المعاملات" أدناه لمزيد من المعلومات.
يضبط قائمة params في سياق MD ctx. انظر "المعاملات" أدناه لمزيد من المعلومات.
تحصل على مصفوفة ثابتة من OSSL_PARAM(3) تصف المعاملات القابلة للاسترجاع التي يمكن استخدامها مع EVP_MD_get_params().
احصل على مصفوفة ثابتة من OSSL_PARAM(3) تصف المعاملات القابلة للاسترجاع التي يمكن استخدامها مع EVP_MD_CTX_get_params(). تُرجع EVP_MD_gettable_ctx_params() المعاملات التي يمكن استرجاعها من الخوارزمية، بينما تُرجع EVP_MD_CTX_gettable_params() المعاملات التي يمكن استرجاعها في الحالة الحالية للسياق.
احصل على مصفوفة ثابتة من OSSL_PARAM(3) تصف المعاملات القابلة للتعيين التي يمكن استخدامها مع EVP_MD_CTX_set_params(). تُرجع EVP_MD_settable_ctx_params() المعاملات التي يمكن تعيينها من الخوارزمية، بينما تُرجع EVP_MD_CTX_settable_params() المعاملات التي يمكن تعيينها في الحالة الحالية للسياق.
يضبط ويمسح ويختبر أعلام ctx. انظر "FLAGS" أدناه لمزيد من المعلومات.
تُجزئ datalen بايت من البيانات في data باستخدام خوارزمية التلخيص name، التي تُجلب باستخدام المعاملين الاختياريين libctx و propq. توضع قيمة التلخيص في md ويُكتب طولها في mdlen إذا لم يكن المؤشر NULL. سيُكتب على الأكثر EVP_MAX_MD_SIZE بايت.
غلاف حول دوال Init_ex و Update و Final_ex للتلخيص. تُجزئ count بايت من البيانات في data باستخدام تلخيص type من ENGINE impl. توضع قيمة التلخيص في md ويُكتب طولها في size إذا لم يكن المؤشر NULL. سيُكتب على الأكثر EVP_MAX_MD_SIZE بايت. إذا كان impl NULL، يُستخدم التطبيق المبدئي لتلخيص type.
يُهيئ سياق التلخيص ctx لاستخدام تلخيص type. يُزود type عادةً بواسطة دالة مثل EVP_sha1()، أو قيمة تُجلب صراحةً بواسطة EVP_MD_fetch(). ctx يجب ألا يكون NULL.

تُضبط المعاملات params على السياق بعد التهيئة.

يمكن أن يكون المعامل type NULL إذا كان ctx قد هُيئ بالفعل باستدعاء آخر لـ EVP_DigestInit_ex() ولم يُعاد ضبطه بواسطة EVP_MD_CTX_reset().

يُهيئ سياق التلخيص ctx لاستخدام تلخيص type. يُزود type عادةً بواسطة دالة مثل EVP_sha1()، أو قيمة تُجلب صراحةً بواسطة EVP_MD_fetch().

إذا كان impl غير NULL، يُستخدم تطبيقه للتلخيص type إن وُجد، وإلا يُستخدم التطبيق المبدئي.

يمكن أن يكون المعامل type NULL إذا كان ctx قد هُيئ بالفعل باستدعاء آخر لـ EVP_DigestInit_ex() ولم يُعاد ضبطه بواسطة EVP_MD_CTX_reset().

يُلخص cnt بايت من البيانات عند d في سياق التلخيص ctx. يمكن استدعاء هذه الدالة عدة مرات على نفس ctx لتلخيص بيانات إضافية.
يسترد قيمة التلخيص من ctx ويضعها في md. إذا كان المعامل s غير NULL، يُكتب عدد بايتات البيانات المكتوبة (أي طول التلخيص) إلى العدد الصحيح عند s، ويُكتب على الأكثر EVP_MAX_MD_SIZE بايت ما لم يسمح تطبيق التلخيص بتغيير حجم التلخيص ويُضبط إلى قيمة أكبر بواسطة التطبيق. بعد استدعاء EVP_DigestFinal_ex() لا يمكن إجراء استدعاءات إضافية لـ EVP_DigestUpdate()، ولكن يمكن استدعاء EVP_DigestInit_ex2() لتهيئة عملية تلخيص جديدة. ctx يجب ألا يكون NULL.
واجهات لدوال المخرجات القابلة للتمديد، XOFs، مثل SHAKE128 وSHAKE256. تسترد قيمة التلخيص من ctx وتضعها في out بحجم outlen. بعد استدعاء هذه الدالة لا يمكن إجراء استدعاءات إضافية لـ EVP_DigestUpdate()، ولكن يمكن استدعاء EVP_DigestInit_ex2() لتهيئة عملية جديدة. يمكن استدعاء EVP_DigestFinalXOF() مرة واحدة فقط
مشابه لـ EVP_DigestFinalXOF() ولكنه يسمح بإجراء استدعاءات متعددة لعصر بيانات مخرجات متغيرة الطول. لا ينبغي استدعاء EVP_DigestFinalXOF() بعد هذا.
يمكن استخدامها لنسخ حالة ملخص الرسالة من in. هذا مفيد لتجنب استدعاءات EVP_MD_fetch() المتعددة أو إذا كانت كميات كبيرة من البيانات ستُجزّأ والتي تختلف فقط في البايتات الأخيرة.
يمكن استخدامها لنسخ حالة ملخص الرسالة من in إلى out. هذا مفيد إذا كانت كميات كبيرة من البيانات ستُجزّأ والتي تختلف فقط في البايتات الأخيرة.
تتصرف بنفس طريقة EVP_DigestInit_ex2() باستثناء أنها لا تعين أي معاملات وتستدعي EVP_MD_CTX_reset() لذا لا يمكن استخدامها مع type قيمته NULL.
مشابهة لـ EVP_DigestFinal_ex() باستثناء أنه بعد حساب الملخص، يُنظف سياق الملخص ctx آليًا باستخدام EVP_MD_CTX_reset().
مشابهة لـ EVP_MD_CTX_copy_ex() باستثناء أن الوجهة out لا تحتاج إلى أن تكون مهيأة.
تُرجع 1 إذا كان md تطبيقًا لخوارزمية يمكن تعريفها بـ name، وإلا تُرجع 0.

إذا كان md ملخصًا قديمًا (فهو القيمة المُرجَعة من أمثال EVP_sha256() بدلاً من نتيجة EVP_MD_fetch())، فسيتم اعتبار أسماء المُعمِّيات المسجلة مع سياق المكتبة المبدئي فقط (انظر OSSL_LIB_CTX(3)).

تُرجع 1 إذا كان md دالة إخراج قابلة للتمديد (XOF) وإلا تُرجع 0. SHAKE128 و SHAKE256 هما دالتا XOF. تُرجع 0 لخوارزميات BLAKE2B.
أعد اسم ملخص الرسالة المُعطى. بالنسبة لملخصات الرسائل المُجلَبة بأسماء متعددة، يُرجع واحد منها فقط؛ يُوصى باستخدام EVP_MD_names_do_all() بدلاً من ذلك.
يجتاز جميع أسماء md، ويستدعي fn مع كل اسم وdata. هذا مفيد فقط معEVP_MD المُستجلَبة.
تُرجع وصفًا لملخّص الرسالة، مخصص للعرض والاستهلاك البشري. الوصف متروك لتطبيق الملخّص.
تُرجع مؤشرًا من نوع OSSL_PROVIDER إلى المُزوّد الذي يُنفّذ EVP_MD المُعطى.
تُرجع حجم ملخّص الرسالة عند تمرير EVP_MD، أي حجم التجزئة. قد تحدث قيمة سالبة أو 0 لحجم غير صالح. بالنسبة لـ XOF بدون حجم مبدئي، تُرجع هذه 0.
بالنسبة لملخّص عادي، هذا هو نفسه EVP_MD_get_size(). بالنسبة لـ XOF، تُرجع هذه "xoflen" إذا كان قد وُضع، وإلا تُرجع 0.
تُرجع حجم الكتلة لملخّص الرسالة عند تمرير بنية EVP_MD أو EVP_MD_CTX.
تُرجع NID لمُعرّف الكائن (OBJECT IDENTIFIER) الذي يمثّل ملخّص الرسالة المُعطى عند تمرير بنية EVP_MD. مثلاً، "EVP_MD_get_type(EVP_sha1())" يُرجع NID_sha1. تُستخدم هذه الدالة عادةً عند تعيين مُعرّفات ASN1 OIDs.
تُرجع البيانات الخاصة بطريقة الملخّص لـ EVP_MD_CTX المُمرّر. تُخصّص المساحة بواسطة OpenSSL ولها الحجم المُعيّن أصلاً بـ EVP_MD_meth_set_app_datasize().
تُرجع EVP_MD_CTX_get0_md() بنية EVP_MD المُقابلة لـ EVP_MD_CTX المُمرّر. سيكون هذا نفس كائن EVP_MD المُمرّر أصلاً إلى EVP_DigestInit_ex2() (أو دالة مشابهة أخرى) عند تهيئة EVP_MD_CTX لأول مرة. لاحظ أنه عند استخدام الجلب الصريح (انظر EVP_MD_fetch(3))، لن يُزاد عدد مراجع القيمة المُرجعة من هذه الدالة، وبالتالي لا ينبغي استخدامها بعد تحرير EVP_MD_CTX. EVP_MD_CTX_get1_md() مماثلة باستثناء أن الملكية تُنقل إلى المُستدعي وتكون من EVP_MD_CTX المُمرّر.
تضبط دالة التحديث لـ ctx إلى update. هذه هي الدالة التي تُستدعى بواسطة EVP_DigestUpdate(). إذا لم تُضبط، تُستخدم دالة التحديث من نوع EVP_MD المُحدّد عند التهيئة.
تُرجع دالة التحديث لـ ctx.
تُرجع أعلام md. لاحظ أنها تختلف عن أعلام EVP_MD_CTX. انظر EVP_MD_meth_set_flags(3) لمزيد من المعلومات.
تُرجع NID لخوارزمية توقيع المفتاح العمومي المرتبطة بهذا المُعمّي. على سبيل المثال، EVP_sha1() مرتبط بـ RSA لذا سترجع NID_sha1WithRSAEncryption. نظرًا لأن المُعمّيات وخوارزميات التوقيع لم تعد مرتبطة، فقد احتُفظ بهذه الدالة لأسباب التوافق فقط.
مُعمّي رسالة "فارغ" لا يفعل شيئًا: أي أن التجزئة التي يُرجعها طولها صفر.
تُرجع بنية EVP_MD عند تمرير اسم مُعمّي، أو NID لمُعمّي، أو بنية ASN1_OBJECT على التوالي.

دالة EVP_get_digestbyname() موجودة للتوافق مع الإصدارات السابقة لـ OpenSSL قبل الإصدار 3 وتختلف عن دالة EVP_MD_fetch() لأنها لا تحاول "جلب" تنفيذ للمُعمّي. بالإضافة إلى ذلك، فهي تعرف فقط المُعمّيات المضمنة في OpenSSL والتي لها NID مرتبط. وبالمثل، تُرجع EVP_get_digestbynid() و EVP_get_digestbyobj() كائنات بدون تنفيذ مرتبط.

عند استخدام كائنات المُعمّي التي تُرجعها هذه الدوال (مثل استدعاء EVP_DigestInit_ex())، سيُجلب ضمنيًا تنفيذ للمُعمّي من المزوّدات المُحمّلة. قد يفشل هذا الجلب إذا لم يتوفر تنفيذ مناسب. استخدم EVP_MD_fetch() بدلاً من ذلك لجلب الخوارزمية والتنفيذ المرتبط صراحةً من مزوّد.

انظر "ALGORITHM FETCHING" في crypto(7) لمزيد من المعلومات حول الجلب.

لا تحتاج كائنات المُعمّي التي تُرجعها هذه الدوال إلى تحريرها باستخدام EVP_MD_free().

تُرجع EVP_PKEY_CTX المُسند إلى ctx. لا ينبغي للمستدعي تحرير المؤشر المُرجَع.
تُسند EVP_PKEY_CTX إلى EVP_MD_CTX. يُستخدم هذا عادةً لتوفير EVP_PKEY_CTX مخصص لـ EVP_DigestSignInit(3) أو EVP_DigestVerifyInit(3). يجب على المستدعي تحرير pctx المُمرّر لهذه الدالة. يُسمح أيضًا بمؤشر pctx بقيمة NULL لمسح EVP_PKEY_CTX المُسند إلى ctx. في هذه الحالة، يعتمد تحرير EVP_PKEY_CTX الذي مُسح أم لا على كيفية إنشاء EVP_PKEY_CTX.
يجتاز جميع ملخصات الرسائل المنفذة بواسطة جميع المزوّدات المفعلة في سياق المكتبة libctx، وبالنسبة لكل تنفيذ، يستدعي الدالة fn مع أسلوب التنفيذ وarg المُعطى كوسيط.

المعاملات

انظر OSSL_PARAM(3) لمعلومات حول تمرير المعاملات.

EVP_MD_CTX_set_params() و EVP_MD_CTX_get_params() يمكن استخدامهما مع المفاتيح OSSL_PARAM التالية:

"xoflen" (OSSL_DIGEST_PARAM_XOFLEN) <عدد صحيح غير موقع>
يضبط أو يحصل على طول الملخص لدوال الإخراج القابلة للتمديد. يجب ألا تتجاوز القيمة ما يمكن إعطاؤه باستخدام size_t. قد يُستخدم بواسطة SHAKE-128 و SHAKE-256 لضبط طول الإخراج المستخدم بواسطة EVP_DigestFinal_ex() و EVP_DigestFinal().
"size" (OSSL_DIGEST_PARAM_SIZE) <عدد صحيح غير موقع>
يضبط أو يحصل على طول ملخص ثابت. يجب ألا تتجاوز القيمة ما يمكن إعطاؤه باستخدام size_t. قد يُستخدم بواسطة BLAKE2B-512 لضبط طول الإخراج المستخدم بواسطة EVP_DigestFinal_ex() و EVP_DigestFinal().

EVP_MD_CTX_set_params() يمكن استخدامه مع المفاتيح OSSL_PARAM التالية:

"pad-type" (OSSL_DIGEST_PARAM_PAD_TYPE) <عدد صحيح غير موقع>
يضبط نوع الحشو. يُستخدم بواسطة خوارزمية MDC2.

EVP_MD_CTX_get_params() يمكن استخدامه مع المفاتيح OSSL_PARAM التالية:

"micalg" (OSSL_DIGEST_PARAM_MICALG) <سلسلة محارف UTF8>.
يحصل على سلسلة محارف خوارزمية فحص تكامل الرسالة للملخص. يُستخدم هذا عند إنشاء رسائل S/MIME متعددة الأجزاء/موقعة، كما هو محدد في RFC 3851. قد يُستخدم بواسطة محركات أو مزودات خارجية.

عناصر التحكم

EVP_MD_CTX_ctrl() يمكن استخدامه لإرسال عناصر التحكم القياسية التالية:

يحصل على سلسلة محارف خوارزمية فحص تكامل الرسالة للملخص. يُستخدم هذا عند إنشاء رسائل S/MIME متعددة الأجزاء/موقعة، كما هو محدد في RFC 3851. تُكتب قيمة السلسلة المحارف إلى p2.

عند استخدامه مع EVP_MD مُستَحضَر، يُستدعى EVP_MD_CTX_get_params() مع عنصر OSSL_PARAM(3) بمفتاح "micalg" (OSSL_DIGEST_PARAM_MICALG).

يُعيّن عنصر التحكم هذا طول الملخص لدوال الإخراج القابلة للتمديد إلى p1. لا ينبغي أن يكون إرسال عنصر التحكم هذا مباشرة ضروريًا، ويُفضّل استخدام EVP_DigestFinalXOF(). يُستخدم حاليًا بواسطة خوارزميات SHAKE.

عند استخدامه مع EVP_MD مُستَحضَر، يُستدعى EVP_MD_CTX_get_params() مع عنصر OSSL_PARAM(3) بمفتاح "xoflen" (OSSL_DIGEST_PARAM_XOFLEN).

الأعلام

يمكن استخدام EVP_MD_CTX_set_flags() و EVP_MD_CTX_clear_flags() و EVP_MD_CTX_test_flags() لمعالجة واختبار أعلام EVP_MD_CTX هذه:

يُوجّه هذا العلم الملخص للتحسين لتحديث واحد فقط، إن أمكن.
هذا العلم للاستخدام الداخلي فقط ويجب ألا يُستخدم في كود المستخدم.
هذا العلم للاستخدام الداخلي فقط ويجب ألا يُستخدم في كود المستخدم.
يُوجّه هذا العلم EVP_DigestInit() وما شابهه بعدم تهيئة البيانات الخاصة بالتنفيذ.
بعض الدوال مثل EVP_DigestSign تُنهي فقط نسخًا من السياقات الداخلية بحيث يمكن تضمين بيانات إضافية بعد استدعاء الإنهاء. هذا غير فعال إذا لم تكن هذه الوظيفة مطلوبة، ويمكن تعطيلها بهذا العلم.

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

يُعيد مؤشرًا إلى EVP_MD عند النجاح أو NULL عند الفشل.
يُعيد 1 عند النجاح أو 0 عند الفشل.
تُعيد 1 عند النجاح و 0 عند الفشل.
يُعيد 1 إذا نجح أو 0 عند الفشل.
يُعيد 1 إذا نجح أو 0 عند الفشل.
تُعيد مصفوفة من ثوابت OSSL_PARAM(3)، أو NULL إذا لم يوجد أي منها للحصول عليه.
تُعيد كائن EVP_MD_CTX جديد إذا نجحت أو NULL عند الفشل.
يُعيد 1 إذا نجح أو 0 عند الفشل.
تُعيد NID لمُعرِّف الكائن المُناظر أو NID_undef إذا لم يوجد أي منها.
تُعيد حجم المُستخلص أو الكتلة بالبايت أو -1 عند الفشل.
تُعيد مؤشرًا إلى بنية EVP_MD لمُستخلص الرسالة "الفارغ".
تُعيد إما بنية EVP_MD أو NULL إذا حدث خطأ.
لا قيمة إرجاع لهذه الدالة.
تُعيد 1 إذا استُدعي الاستدعاء لجميع الأسماء. قيمة الإرجاع 0 تعني أن الاستدعاء لم يُستدعَ لأي اسم.

ملاحظات

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

يجب على التطبيقات الجديدة استخدام خوارزميات SHA-2 (مثل EVP_sha256(3)) أو SHA-3 (مثل EVP_sha3_512(3)). لا تزال خوارزميات المُستخلص الأخرى شائعة الاستخدام.

بالنسبة لمعظم التطبيقات، يُضبط المُعامل impl في EVP_DigestInit_ex() على NULL لاستخدام التنفيذ المبدئي للمُستخلص.

تجاهل قيم الإرجاع الفاشلة لـ EVP_DigestInit_ex() أو EVP_DigestInit_ex2() أو EVP_DigestInit() قد يؤدي إلى سلوك غير مُحدد في الاستدعاءات اللاحقة لتحديث أو إنهاء EVP_MD_CTX مثل دوال EVP_DigestUpdate() أو EVP_DigestFinal(). الاستدعاءات الصالحة الوحيدة على EVP_MD_CTX عند فشل التهيئة هي استدعاءات تُحاول تهيئة أخرى للسياق أو تحرير السياق.

الدوال EVP_DigestInit() و EVP_DigestFinal() و EVP_MD_CTX_copy() قديمة لكنها محفوظة للحفاظ على التوافق مع الشيفرة الموجودة. يجب على التطبيقات الجديدة استخدام EVP_DigestInit_ex() و EVP_DigestFinal_ex() و EVP_MD_CTX_copy_ex() لأنها تستطيع إعادة استخدام سياق التقطيع بكفاءة بدلاً من تهيئته وتنظيفه في كل استدعاء وتسمح بتحديد تطبيقات غير مبدئية للتقطيع.

إذا لم تُنظف سياقات التقطيع بعد الاستخدام، ستحدث تسريبات للذاكرة.

EVP_MD_CTX_get0_name() و EVP_MD_CTX_get_size() و EVP_MD_CTX_get_block_size() و EVP_MD_CTX_get_type() و EVP_get_digestbynid() و EVP_get_digestbyobj() معرّفة كوحدات ماكرو.

EVP_MD_CTX_ctrl() تُرسل أوامر إلى تقطيعات الرسائل لتكوين أو تحكم إضافي.

أمثلة

هذا المثال يقطع البيانات "Test Message\n" و "Hello World\n"، باستخدام اسم التقطيع المُمرّر عبر سطر الأوامر.

 #include <stdio.h>
 #include <string.h>
 #include <openssl/evp.h>
 int main(int argc, char *argv[])
 {
     EVP_MD_CTX *mdctx;
     const EVP_MD *md;
     char mess1[] = "Test Message\n";
     char mess2[] = "Hello World\n";
     unsigned char md_value[EVP_MAX_MD_SIZE];
     unsigned int md_len, i;
     if (argv[1] == NULL) {
         printf("Usage: mdtest digestname\n");
         exit(1);
     }
     md = EVP_get_digestbyname(argv[1]);
     if (md == NULL) {
         printf("Unknown message digest %s\n", argv[1]);
         exit(1);
     }
     mdctx = EVP_MD_CTX_new();
     if (mdctx == NULL) {
        printf("Message digest create failed.\n");
        exit(1);
     }
     if (!EVP_DigestInit_ex2(mdctx, md, NULL)) {
         printf("Message digest initialization failed.\n");
         EVP_MD_CTX_free(mdctx);
         exit(1);
     }
     if (!EVP_DigestUpdate(mdctx, mess1, strlen(mess1))) {
         printf("Message digest update failed.\n");
         EVP_MD_CTX_free(mdctx);
         exit(1);
     }
     if (!EVP_DigestUpdate(mdctx, mess2, strlen(mess2))) {
         printf("Message digest update failed.\n");
         EVP_MD_CTX_free(mdctx);
         exit(1);
     }
     if (!EVP_DigestFinal_ex(mdctx, md_value, &md_len)) {
         printf("Message digest finalization failed.\n");
         EVP_MD_CTX_free(mdctx);
         exit(1);
     }
     EVP_MD_CTX_free(mdctx);
     printf("Digest is: ");
     for (i = 0; i < md_len; i++)
         printf("%02x", md_value[i]);
     printf("\n");
     exit(0);
 }

انظر أيضًا

EVP_MD_meth_new(3), openssl-dgst(1), evp(7), OSSL_PROVIDER(3), OSSL_PARAM(3), property(7), "جلب الخوارزميات" في crypto(7), provider-digest(7), life_cycle-digest(7)

القائمة الكاملة لخوارزميات التقطيع مُقدّمة أدناه.

EVP_blake2b512(3), EVP_md2(3), EVP_md4(3), EVP_md5(3), EVP_mdc2(3), EVP_ripemd160(3), EVP_sha1(3), EVP_sha224(3), EVP_sha3_224(3), EVP_sm3(3), EVP_whirlpool(3)

التاريخ

الدالتان EVP_MD_CTX_create() و EVP_MD_CTX_destroy() أُعيدت تسميتهما إلى EVP_MD_CTX_new() و EVP_MD_CTX_free() في OpenSSL 1.1.0، على التوالي.

الرابط بين التقطيعات وخوارزميات التوقيع ثُبّت في OpenSSL 1.0 وما بعده، لذا الآن يمكن استخدام EVP_sha1() مع RSA و DSA.

الدالة EVP_dss1() أُزيلت في OpenSSL 1.1.0.

الدالة EVP_MD_CTX_set_pkey_ctx() أُضيفت في OpenSSL 1.1.1.

الدوال EVP_Q_digest() و EVP_DigestInit_ex2() و EVP_MD_fetch() و EVP_MD_free() و EVP_MD_up_ref() و EVP_MD_get_params() و EVP_MD_CTX_set_params() و EVP_MD_CTX_get_params() و EVP_MD_gettable_params() و EVP_MD_gettable_ctx_params() و EVP_MD_settable_ctx_params() و EVP_MD_CTX_settable_params() و EVP_MD_CTX_gettable_params() أُضيفت في OpenSSL 3.0.

الدوال EVP_MD_type() و EVP_MD_nid() و EVP_MD_name() و EVP_MD_pkey_type() و EVP_MD_size() و EVP_MD_block_size() و EVP_MD_flags() و EVP_MD_CTX_size() و EVP_MD_CTX_block_size() و EVP_MD_CTX_type() و EVP_MD_CTX_md_data() أُعيدت تسميتها لتضمين "get" أو "get0" في أسمائها في OpenSSL 3.0، على التوالي. الأسماء القديمة محفوظة كوحدات ماكرو بديلة غير مهملة.

الدالة EVP_MD_CTX_md() أُهملت في OpenSSL 3.0؛ استخدم EVP_MD_CTX_get0_md() بدلاً منها. EVP_MD_CTX_update_fn() و EVP_MD_CTX_set_update_fn() أُهملتا في OpenSSL 3.0.

الدالة EVP_MD_CTX_dup() أُضيفت في OpenSSL 3.1.

الدالة EVP_DigestSqueeze() أُضيفت في OpenSSL 3.3.

الدالتان EVP_MD_CTX_get_size_ex() و EVP_xof() أُضيفتا في OpenSSL 3.4. وحدات الماكرو EVP_MD_CTX_get_size() و EVP_MD_CTX_size غُيّرت في OpenSSL 3.4 لتكون أسماء مستعارة لـ EVP_MD_CTX_get_size_ex()، سابقاً كانت أسماء مستعارة لـ EVP_MD_get_size التي كانت تُرجع قيمة ثابتة. هذا مطلوب لتقطيعات XOF لأنها ليس لها حجم ثابت.

حقوق النسخ

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

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

ترجمة

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

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

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

7 أبريل 2026 3.6.2