الاسم¶

X509_STORE_CTX_new_ex, X509_STORE_CTX_new, X509_STORE_CTX_cleanup, X509_STORE_CTX_free, X509_STORE_CTX_init, X509_STORE_CTX_init_rpk, X509_STORE_CTX_set0_trusted_stack, X509_STORE_CTX_set_cert, X509_STORE_CTX_set0_crls, X509_STORE_CTX_set0_rpk, X509_STORE_CTX_get0_param, X509_STORE_CTX_set0_param, X509_STORE_CTX_get0_untrusted, X509_STORE_CTX_set0_untrusted, X509_STORE_CTX_get_num_untrusted, X509_STORE_CTX_get0_chain, X509_STORE_CTX_set0_verified_chain, X509_STORE_CTX_get0_rpk, X509_STORE_CTX_set_default, X509_STORE_CTX_set_verify, X509_STORE_CTX_verify_fn, X509_STORE_CTX_set_ocsp_resp, X509_STORE_CTX_set_purpose, X509_STORE_CTX_set_trust, X509_STORE_CTX_purpose_inherit - تهيئة X509_STORE_CTX

موجز¶

 #include <openssl/x509_vfy.h>
 X509_STORE_CTX *X509_STORE_CTX_new_ex(OSSL_LIB_CTX *libctx, const char *propq);
 X509_STORE_CTX *X509_STORE_CTX_new(void);
 void X509_STORE_CTX_cleanup(X509_STORE_CTX *ctx);
 void X509_STORE_CTX_free(X509_STORE_CTX *ctx);
 int X509_STORE_CTX_init(X509_STORE_CTX *ctx, X509_STORE *trust_store,
                         X509 *target, STACK_OF(X509) *untrusted);
 int X509_STORE_CTX_init_rpk(X509_STORE_CTX *ctx, X509_STORE *trust_store,
                             EVP_PKEY *rpk);
 void X509_STORE_CTX_set0_trusted_stack(X509_STORE_CTX *ctx, STACK_OF(X509) *sk);
 void X509_STORE_CTX_set_cert(X509_STORE_CTX *ctx, X509 *target);
 void X509_STORE_CTX_set0_crls(X509_STORE_CTX *ctx, STACK_OF(X509_CRL) *sk);
 void X509_STORE_CTX_set0_rpk(X509_STORE_CTX *ctx, EVP_PKEY *target);
 X509_VERIFY_PARAM *X509_STORE_CTX_get0_param(const X509_STORE_CTX *ctx);
 void X509_STORE_CTX_set0_param(X509_STORE_CTX *ctx, X509_VERIFY_PARAM *param);
 STACK_OF(X509)* X509_STORE_CTX_get0_untrusted(const X509_STORE_CTX *ctx);
 void X509_STORE_CTX_set0_untrusted(X509_STORE_CTX *ctx, STACK_OF(X509) *sk);
 int X509_STORE_CTX_get_num_untrusted(const X509_STORE_CTX *ctx);
 STACK_OF(X509) *X509_STORE_CTX_get0_chain(const X509_STORE_CTX *ctx);
 void X509_STORE_CTX_set0_verified_chain(X509_STORE_CTX *ctx, STACK_OF(X509) *chain);
 EVP_PKEY *X509_STORE_CTX_get0_rpk(const X509_STORE_CTX *ctx);
 int X509_STORE_CTX_set_default(X509_STORE_CTX *ctx, const char *name);
 typedef int (*X509_STORE_CTX_verify_fn)(X509_STORE_CTX *);
 void X509_STORE_CTX_set_verify(X509_STORE_CTX *ctx, X509_STORE_CTX_verify_fn verify);
 void X509_STORE_CTX_set_ocsp_resp(X509_STORE_CTX *ctx, STACK_OF(OCSP_RESPONSE) *sk);
 int X509_STORE_CTX_set_purpose(X509_STORE_CTX *ctx, int purpose);
 int X509_STORE_CTX_set_trust(X509_STORE_CTX *ctx, int trust);
 int X509_STORE_CTX_purpose_inherit(X509_STORE_CTX *ctx, int def_purpose,
                                    int purpose, int trust);

الوصف¶

تُهيئ هذه الدوال بنية X509_STORE_CTX للاستخدام اللاحق بواسطة X509_verify_cert(3) أو X509_STORE_CTX_verify(3).

تُرجع X509_STORE_CTX_new_ex() بنية X509_STORE_CTX مُهيأة حديثًا مرتبطة بسياق المكتبة المحدد libctx وسلسلة استعلام الخاصية propq. أي خوارزميات تعمية تُجلب أثناء المعالجة باستخدام X509_STORE_CTX ستستخدم سياق المكتبة وسلسلة استعلام الخاصية تلك.

X509_STORE_CTX_new() مماثلة لـ X509_STORE_CTX_new_ex() باستثناء استخدام سياق المكتبة المبدئي وسلسلة استعلام خاصية NULL.

تنظف X509_STORE_CTX_cleanup() داخليًا بنية X509_STORE_CTX. تُستخدم بواسطة X509_STORE_CTX_init() و X509_STORE_CTX_free().

تحرر X509_STORE_CTX_free() ctx بالكامل. بعد هذه الاستدعاء، لم يعد ctx صالحًا. إذا كان ctx هو NULL، لا يُفعل شيء.

تُعد X509_STORE_CTX_init() ctx لعملية تحقق لاحقة.

تهيئ X509_STORE_CTX_init() الحالة الداخلية والموارد لـ ctx المُعطى. من بين أمور أخرى، تضبط معاملات التحقق المرتبطة باسم الطريقة "default"، والتي تتضمن الغرض "any"، وتستحوذ على مؤشرات دالة الاستدعاء من trust_store (إلا إذا كان NULL). يجب استدعاؤها قبل كل استدعاء لـ X509_verify_cert(3) أو X509_STORE_CTX_verify(3)، أي أن السياق صالح فقط لعملية تحقق واحدة. إذا أردت التحقق من شهادة أو سلسلة إضافية باستخدام نفس ctx، فيجب استدعاء X509_STORE_CTX_init() مرة أخرى. يُضبط مخزن الشهادات الموثوقة إلى trust_store من النوع X509_STORE. قد يكون هذا NULL إما لعدم وجود شهادات موثوقة أو لأنها مُقدمة ببساطة كقائمة باستخدام X509_STORE_CTX_set0_trusted_stack(). تُضبط الشهادة المراد التحقق منها إلى target، ويمكن توفير قائمة بشهادات إضافية في untrusted، والتي ستكون غير موثوقة ولكن قد تُستخدم لبناء السلسلة. لا تُنسخ شهادة target (لا يُحدث عدد مراجعها)، ويجب على المستدعي عدم تحريرها قبل اكتمال التحقق. يمكن أن يكون كل من معاملات trust_store و target و untrusted NULL. لكن لاحظ أن X509_verify_cert(3) و X509_STORE_CTX_verify(3) ستحتاج إلى هدف تحقق. يمكن أيضًا ضبط هذا باستخدام X509_STORE_CTX_set_cert(). بالنسبة لـ X509_STORE_CTX_verify(3)، التي تأخذ مبدئيًا العنصر الأول من قائمة الشهادات غير الموثوقة كهدف تحقق لها، يمكن ضبط هذا أيضًا بشكل غير مباشر باستخدام X509_STORE_CTX_set0_untrusted().

X509_STORE_CTX_init_rpk() يُهيئ ctx لعملية تحقق لاحقة للمفتاح العام الخام target. يتصرف بشكل مشابه لـ X509_STORE_CTX_init(). يمكن أيضًا توفير المفتاح العام الخام target بشكل منفصل، عبر X509_STORE_CTX_set0_rpk(). لا يُنسخ المفتاح العام target (لا يُحدث عدد مرجعه)، ويجب على المستدعي ألا يحرره قبل اكتمال التحقق.

X509_STORE_CTX_set0_trusted_stack() يضبط مجموعة الشهادات الموثوقة لـ ctx إلى sk. هذه طريقة بديلة لتحديد الشهادات الموثوقة بدلاً من استخدام X509_STORE حيث لا تكون تعقيداته مطلوبة أو للتأكد من أن المجموعة المعطاة sk من الشهادات فقط هي الموثوقة.

X509_STORE_CTX_set_cert() يضبط الشهادة الهدف المراد التحقق منها في ctx إلى target. لا تُنسخ الشهادة الهدف (لا يُحدث عدد مرجعها)، ويجب على المستدعي ألا يحررها قبل اكتمال التحقق.

X509_STORE_CTX_set0_rpk() يضبط المفتاح العام الخام الهدف المراد التحقق منه في ctx إلى target، المفتاح العام الخام غير NULL يسبق أي شهادة هدف، والتي تُتجاهل بعد ذلك. لا يُنسخ المفتاح العام target (لا يُحدث عدد مرجعه)، ويجب على المستدعي ألا يحرره قبل اكتمال التحقق.

X509_STORE_CTX_set0_verified_chain() تضبط السلسلة المُتحقق منها إلى chain. تُنقل ملكية السلسلة إلى ctx، لذا لا ينبغي تحريرها من قبل المُستدعي.

X509_STORE_CTX_get0_chain() يُرجع المؤشر الداخلي المستخدم من قبل ctx الذي يحتوي على السلسلة المُنشأة (الناتجة).

X509_STORE_CTX_get0_rpk() يُرجع المؤشر الداخلي المستخدم من قبل ctx الذي يحتوي على المفتاح العام الخام.

X509_STORE_CTX_set0_crls() يضبط مجموعة من قوائم إلغاء الشهادات (CRLs) لاستخدامها للمساعدة في التحقق من الشهادة إلى sk. ستُستخدم قوائم إلغاء الشهادات هذه فقط إذا كان التحقق من قائمة إلغاء الشهادات مفعلاً في بنية X509_VERIFY_PARAM المرتبطة. قد يُستخدم هذا حيث يتم توفير قوائم إلغاء شهادات إضافية "مفيدة" كجزء من بروتوكول، على سبيل المثال في بنية PKCS#7.

X509_STORE_CTX_get0_param() يسترجع مؤشرًا داخليًا إلى معاملات التحقق المرتبطة بـ ctx.

X509_STORE_CTX_set0_param() يُعيِّن مؤشر معامل التحقق الداخلي إلى param. بعد هذه الاستدعاء، لا ينبغي استخدام param.

X509_STORE_CTX_get0_untrusted() يسترجع مؤشرًا داخليًا إلى رصة الشهادات غير الموثوقة المرتبطة بـ ctx.

X509_STORE_CTX_set0_untrusted() يُعيِّن المؤشر الداخلي إلى رصة الشهادات غير الموثوقة المرتبطة بـ ctx إلى sk. X509_STORE_CTX_verify() سيأخذ العنصر الأول، إن وُجد، كهدف مبدئي له إذا لم يُعيَّن الشهادة الهدف بشكل صريح.

X509_STORE_CTX_get_num_untrusted() يُرجع عدد الشهادات غير الموثوقة التي استُخدمت في بناء السلسلة. يمكن استخدام هذا بعد استدعاء X509_verify_cert(3) والدوال المماثلة. مع X509_STORE_CTX_verify(3)، لا يُحتسب هذا العنصر الأول من السلسلة.

X509_STORE_CTX_get0_chain() يُرجع المؤشر الداخلي المستخدم بواسطة ctx الذي يحتوي على السلسلة المُتحقق منها.

تفاصيل عملية بناء السلسلة والتحقق منها موصوفة في "بناء مسار الشهادة" في openssl-verification-options(1) و"التحقق من صحة مسار الشهادة" في openssl-verification-options(1).

X509_STORE_CTX_set0_verified_chain() تضبط السلسلة المُتحقق منها المُستخدمة بواسطة ctx لتكون chain. تُنقل ملكية السلسلة إلى ctx، لذا لا ينبغي تحريرها من قبل المُستدعي.

X509_STORE_CTX_set_default() يبحث ويُعيِّن طريقة التحقق المبدئية. يستخدم هذا الدالة X509_VERIFY_PARAM_lookup() لإيجاد مجموعة المعاملات المرتبطة بطريقة التحقق المُعطاة name. من بين أمور أخرى، تُحدد المعاملات نموذج الثقة والغرض من التحقق. مزيد من التفاصيل، بما في ذلك قائمة الطرق المُحددة مسبقًا حاليًا، موصوفة لخيار سطر الأوامر -verify_name في "خيارات التحقق" في openssl-verification-options(1).

X509_STORE_CTX_set_verify() يُوفر القدرة على تجاوز دالة التحقق المبدئية. هذه الدالة مسؤولة عن التحقق من توقيعات السلسلة وأوقات انتهاء الصلاحية.

دالة التحقق مُعرَّفة كنوع X509_STORE_CTX_verify الذي له التوقيع التالي:

 int (*verify)(X509_STORE_CTX *);

يجب أن تستقبل هذه الدالة X509_STORE_CTX الحالي كمعامل وتُرجع 1 عند النجاح أو 0 عند الفشل.

قد تحتوي شهادات X509 على معلومات حول الأغراض التي يمكن استخدام المفاتيح الموجودة فيها من أجلها. على سبيل المثال "الاستيثاق لخادم ويب TLS" أو "حماية البريد الإلكتروني". معلومات "استخدام المفتاح" هذه محفوظة داخليًا في الشهادة نفسها. بالإضافة إلى ذلك، يمكن لمخزن الثقة الذي يحتوي على شهادات موثوقة أن يُعلن عن الأغراض التي نثق بها في شهادات مختلفة. معلومات "الثقة" هذه ليست محفوظة داخل الشهادة نفسها بل هي معلومات "فوقية" محفوظة بجانبها. ترتبط هذه المعلومات "الفوقية" بالشهادة بعد إصدارها ويمكن أن يُحددها مسؤول النظام. على سبيل المثال، قد تُعلن شهادة أنها مناسبة للاستخدام لكل من "الاستيثاق لخادم ويب TLS" و"الاستيثاق لعميل TLS"، لكن مسؤول النظام قد يثق بها فقط للأول. يوجد امتداد لشهادة X.509 يمكنه تسجيل معلومات استخدام المفتاح الموسعة لتكملة معلومات الغرض الموصوفة أعلاه. هذه الآلية الموسعة قابلة للتوسع بشكل تعسفي وغير مناسبة لواجهة برمجة تطبيقات مكتبة عامة؛ التطبيقات التي تحتاج إلى التحقق من معلومات استخدام المفتاح الموسعة في الشهادات ستحتاج إلى تعريف "غرض" مخصص (انظر أدناه) أو توفير رد اتصال تحقق غير مبدئي (X509_STORE_set_verify_cb_func(3)).

X509_STORE_CTX_set_ocsp_resp() يُعيِّن استجابة (استجابات) OCSP للتحقق من سلسلة شهادات أو لتضمينها في مصافحة TLS، عندما يطلب العميل تدبيس OCSP. رصة استجابات OCSP sk لا تُنسخ بل تُخزَّن فقط في السياق. ctx يحمل مؤشرًا إلى الرصة، لذا يجب أن تعمر الرصة أكثر من ctx.

X509_STORE_CTX_set_purpose() يُعيِّن الغرض للشهادة الهدف التي يتم التحقق منها في ctx. القيم المدمجة المتاحة لوسيط purpose هي X509_PURPOSE_SSL_CLIENT، X509_PURPOSE_SSL_SERVER، X509_PURPOSE_NS_SSL_SERVER، X509_PURPOSE_SMIME_SIGN، X509_PURPOSE_SMIME_ENCRYPT، X509_PURPOSE_CRL_SIGN، X509_PURPOSE_ANY، X509_PURPOSE_OCSP_HELPER، X509_PURPOSE_TIMESTAMP_SIGN و X509_PURPOSE_CODE_SIGN. من الممكن أيضًا إنشاء قيمة غرض مخصصة. يُطلب تعيين غرض التحقق من أن امتدادات استخدام المفتاح واستخدام المفتاح الموسع (EKU) المُعلنة اختياريًا داخل الشهادة وسلسلتها متسقة مع ذلك الغرض. لأغراض عميل SSL وخادم SSL وS/MIME، يُفحص EKU أيضًا لشهادات CA على طول السلسلة، بما في ذلك أي شهادة مرساة ثقة مُعطاة. قد تُجرى أيضًا فحوصات إضافية (اعتمادًا على الغرض المُعطى). كل غرض له أيضًا قيمة ثقة مبدئية مرتبطة، والتي ستُعيَّن أيضًا في نفس الوقت. أثناء التحقق، سيُتحقق من إعداد الثقة هذا لمعرفة ما إذا كان متسقًا مع الثقة التي حددها مسؤول النظام للشهادات في السلسلة.

X509_STORE_CTX_set_trust() يُعيِّن قيمة الثقة للشهادة الهدف التي يتم التحقق منها في ctx. القيم المدمجة المتاحة لوسيط trust هي X509_TRUST_COMPAT، X509_TRUST_SSL_CLIENT، X509_TRUST_SSL_SERVER، X509_TRUST_EMAIL، X509_TRUST_OBJECT_SIGN، X509_TRUST_OCSP_SIGN، X509_TRUST_OCSP_REQUEST و X509_TRUST_TSA. من الممكن أيضًا إنشاء قيمة ثقة مخصصة. نظرًا لأن X509_STORE_CTX_set_purpose() يُعيِّن أيضًا قيمة الثقة، فعادةً ما يكون كافيًا استدعاء تلك الدالة فقط. إذا استُدعيت كلتاهما، فيجب استدعاء X509_STORE_CTX_set_trust() بعد X509_STORE_CTX_set_purpose() لأن إعداد الثقة من آخر استدعاء سيُستخدم.

لا ينبغي عادةً أن يكون من الضروري لتطبيقات المستخدم النهائي استدعاء X509_STORE_CTX_purpose_inherit() مباشرة. عادةً، يجب على التطبيقات استدعاء X509_STORE_CTX_set_purpose() أو X509_STORE_CTX_set_trust() بدلاً من ذلك. باستخدام هذه الدالة، يمكن ضبط قيم الغرض والثقة لـ ctx في نفس الوقت. يجب ألا يكون كل من ctx ومؤشر معامل التحقق الداخلي الخاص به NULL. يمكن أن تحتوي وسيطات def_purpose و purpose على نفس قيم الغرض كما هو موصوف لـ X509_STORE_CTX_set_purpose() أعلاه. يمكن أن تحتوي وسيطة trust على نفس قيم الثقة كما هو موصوف في X509_STORE_CTX_set_trust() أعلاه. قد تحتوي أي من قيم def_purpose أو purpose أو trust أيضًا على القيمة 0 للإشارة إلى أنه يجب تجاهل المعامل المُقدم. بعد استدعاء هذه الدالة، يُضبط الغرض المراد استخدامه للتحقق من وسيطة purpose ما لم يكن الغرض قد ضُبط بالفعل في ctx من قبل، وتُضبط الثقة من وسيطة trust ما لم تكن الثقة قد ضُبطت بالفعل في ctx من قبل. إذا كانت trust تساوي 0، فستُضبط قيمة الثقة من قيمة الثقة المبدئية لـ purpose. إذا كانت قيمة الثقة المبدئية للغرض هي X509_TRUST_DEFAULT و trust تساوي 0، فتُستخدم قيمة الثقة المبدئية المرتبطة بقيمة def_purpose لإعداد الثقة بدلاً من ذلك.

ملاحظات¶

تُستخدم الشهادات وقوائم إلغاء الشهادات في المخزن داخليًا ويجب عدم تحريرها حتى بعد تحرير X509_STORE_CTX المرتبط.

العلل¶

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

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

X509_STORE_CTX_new() يُرجع سياقًا مُخصصًا حديثًا أو NULL إذا حدث خطأ.

X509_STORE_CTX_init() و X509_STORE_CTX_init_rpk() تُعيد 1 عند النجاح أو 0 إذا حدث خطأ.

X509_STORE_CTX_get0_param() تُعيد مؤشرًا إلى بنية X509_VERIFY_PARAM أو NULL إذا حدث خطأ.

X509_STORE_CTX_get0_rpk() تُعيد مؤشرًا إلى بنية EVP_PKEY إذا كانت موجودة، أو NULL إذا كانت غائبة.

X509_STORE_CTX_cleanup()، X509_STORE_CTX_free()، X509_STORE_CTX_set0_trusted_stack()، X509_STORE_CTX_set_cert()، X509_STORE_CTX_set0_crls() و X509_STORE_CTX_set0_param() لا تُعيد قيمًا.

X509_STORE_CTX_set_default() تُعيد 1 عند النجاح أو 0 إذا حدث خطأ.

X509_STORE_CTX_get_num_untrusted() تُعيد عدد الشهادات غير الموثوقة المُستخدمة.

انظر أيضًا¶

X509_verify_cert(3)، X509_STORE_CTX_verify(3)، X509_VERIFY_PARAM_set_flags(3)

التاريخ¶

أُضيفت الدالة X509_STORE_CTX_set0_crls() في OpenSSL 1.0.0. أُضيفت الدالة X509_STORE_CTX_get_num_untrusted() في OpenSSL 1.1.0. أُضيفت الدالة X509_STORE_CTX_new_ex() في OpenSSL 3.0. أُضيفت الدوال X509_STORE_CTX_init_rpk() و X509_STORE_CTX_get0_rpk() و X509_STORE_CTX_set0_rpk() في OpenSSL 3.2. أُضيفت الدالة X509_STORE_CTX_set_ocsp_resp() في OpenSSL 3.6.

لا حاجة لاستدعاء X509_STORE_CTX_cleanup() صراحةً منذ OpenSSL 3.0.

حقوق النسخ¶

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

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

ترجمة¶

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

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

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