الاسم¶

SSL_get_error - الحصول على رمز النتيجة لعملية الإدخال/الإخراج TLS/SSL

موجز¶

 #include <openssl/ssl.h>
 int SSL_get_error(const SSL *ssl, int ret);

الوصف¶

تُرجع SSL_get_error() رمز نتيجة (مناسب لعبارة "switch" في C) لاستدعاء سابق لـ SSL_connect() أو SSL_accept() أو SSL_do_handshake() أو SSL_read_ex() أو SSL_read() أو SSL_peek_ex() أو SSL_peek() أو SSL_shutdown() أو SSL_write_ex() أو SSL_write() على ssl. يجب تمرير القيمة التي أرجعتها دالة الإدخال/الإخراج TLS/SSL تلك إلى SSL_get_error() في المعامل ret.

بالإضافة إلى ssl و ret، تفحص SSL_get_error() طابور أخطاء OpenSSL للخيط الحالي. لذا، يجب استخدام SSL_get_error() في نفس الخيط الذي أجرى عملية الإدخال/الإخراج TLS/SSL، ولا ينبغي ظهور أي استدعاءات دوال OpenSSL أخرى بينهما. يجب أن يكون طابور أخطاء الخيط الحالي فارغًا قبل محاولة عملية الإدخال/الإخراج TLS/SSL، وإلا لن تعمل SSL_get_error() بشكل موثوق. يتم إفراغ طابور أخطاء الخيط الحالي باستخدام ERR_clear_error(3).

ملاحظات¶

بعض تطبيقات TLS لا ترسل تنبيه close_notify عند الإغلاق.

عند مواجهة نهاية ملف غير متوقعة، أرجع الإصدار قبل OpenSSL 3.0 SSL_ERROR_SYSCALL، ولم يُضف شيء إلى مكدس الأخطاء، وكان errno يساوي 0. منذ OpenSSL 3.0، الخطأ المُرجَع هو SSL_ERROR_SSL مع خطأ ذي معنى على مكدس الأخطاء (SSL_R_UNEXPECTED_EOF_WHILE_READING). يمكن استخدام رمز سبب الخطأ هذا لقرارات تدفق التحكم (انظر صفحة الدليل لـ ERR_GET_REASON(3) لمزيد من التفاصيل حول هذا).

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

يمكن أن تحدث قيم الإرجاع التالية حاليًا:

SSL_ERROR_NONE

اكتملت عملية الإدخال/الإخراج TLS/SSL. يُرجع رمز النتيجة هذا إذا وفقط إذا كان ret > 0.

SSL_ERROR_ZERO_RETURN

أغلق النظير TLS/SSL الاتصال للكتابة بإرسال تنبيه close_notify. لا يمكن قراءة المزيد من البيانات. لاحظ أن SSL_ERROR_ZERO_RETURN لا يشير بالضرورة إلى أن النقل الأساسي قد أُغلق.

يمكن أن يظهر هذا الخطأ أيضًا عند تعيين الخيار SSL_OP_IGNORE_UNEXPECTED_EOF. انظر SSL_CTX_set_options(3) لمزيد من التفاصيل.

SSL_ERROR_WANT_READ, SSL_ERROR_WANT_WRITE

لم تكتمل العملية ويمكن إعادة محاولتها لاحقًا.

بالنسبة لكائنات SSL غير QUIC، يُرجع SSL_ERROR_WANT_READ عندما كانت آخر عملية هي عملية قراءة من BIO غير محظور. يعني ذلك أنه لم تكن بيانات كافية متاحة في هذا الوقت لإكمال العملية. إذا توفرت بيانات للقراءة في BIO الأساسي في وقت لاحق، يمكن استدعاء نفس الدالة مرة أخرى.

يمكن لـ SSL_read() و SSL_read_ex() أيضًا تعيين SSL_ERROR_WANT_READ عندما لا تزال هناك بيانات غير معالجة متاحة إما في طبقة SSL أو BIO، حتى بالنسبة لـ BIO محظور. انظر SSL_read(3) لمزيد من المعلومات.

بالنسبة لكائنات SSL غير QUIC، يُرجع SSL_ERROR_WANT_WRITE عندما كانت آخر عملية هي كتابة إلى BIO غير محظور ولم يتمكن من إرسال جميع البيانات إلى BIO. عندما يصبح BIO قابلاً للكتابة مرة أخرى، يمكن استدعاء نفس الدالة مرة أخرى.

لاحظ أن إعادة المحاولة قد تؤدي مرة أخرى إلى حالة SSL_ERROR_WANT_READ أو SSL_ERROR_WANT_WRITE. لا يوجد حد أعلى ثابت لعدد التكرارات التي قد تكون ضرورية حتى يصبح التقدم مرئيًا على مستوى بروتوكول التطبيق.

بالنسبة لكائنات SSL الخاصة بـ QUIC، فإن معنى SSL_ERROR_WANT_READ و SSL_ERROR_WANT_WRITE لهما دلالات مختلفة ولكنها متوافقة إلى حد كبير. نظرًا لأن QUIC ينفذ التحكم في التدفق الخاص به ويستخدم مخططات بيانات UDP، فإن ظروف الضغط العكسي من حيث BIO الأساسي الذي يوفر الإدخال/الإخراج الشبكي ليست ذات صلة مباشرة بالظروف التي تُنتج فيها هذه الأخطاء. على وجه الخصوص، يشير SSL_ERROR_WANT_WRITE إلى أن مخزن الإرسال الداخلي لـ OpenSSL لدفق QUIC معين قد امتلأ. وبالمثل، يشير SSL_ERROR_WANT_READ إلى أن مخزن الاستقبال الداخلي لـ OpenSSL لدفق QUIC معين فارغ.

من الآمن استدعاء SSL_read() أو SSL_read_ex() عند توفر المزيد من البيانات حتى لو كان الاستدعاء الذي عيَّن هذا الخطأ هو SSL_write() أو SSL_write_ex(). لكن، إذا كان الاستدعاء هو SSL_write() أو SSL_write_ex()، فيجب استدعاؤه مرة أخرى لمواصلة إرسال بيانات التطبيق. إذا حصلت على SSL_ERROR_WANT_WRITE من SSL_write() أو SSL_write_ex()، فلا ينبغي لك القيام بأي عملية أخرى قد تُحفِّز IO سوى تكرار استدعاء SSL_write() السابق.

بالنسبة لـ BIOs المقبس (مثلًا عند استخدام SSL_set_fd())، يمكن استخدام select() أو poll() على المقبس الأساسي لمعرفة متى ينبغي إعادة محاولة دالة الإدخال/الإخراج TLS/SSL.

ملاحظة: أي دالة إدخال/إخراج TLS/SSL قد تؤدي إلى أي من SSL_ERROR_WANT_READ و SSL_ERROR_WANT_WRITE. على وجه الخصوص، قد ترغب SSL_read_ex()، SSL_read()، SSL_peek_ex()، أو SSL_peek() في كتابة بيانات وقد ترغب SSL_write() أو SSL_write_ex() في قراءة بيانات. هذا يرجع أساسًا إلى أن مصافحات TLS/SSL قد تحدث في أي وقت أثناء البروتوكول (يبدأها العميل أو الخادم)؛ ستتعامل SSL_read_ex()، SSL_read()، SSL_peek_ex()، SSL_peek()، SSL_write_ex()، و SSL_write() مع أي مصافحات معلقة.

SSL_ERROR_WANT_CONNECT، SSL_ERROR_WANT_ACCEPT

لم تكتمل العملية؛ ينبغي استدعاء نفس دالة الإدخال/الإخراج TLS/SSL لاحقًا. لم يكن BIO الأساسي متصلًا بعد بالنظير وسيحجب الاستدعاء في connect()/accept(). ينبغي استدعاء دالة SSL مرة أخرى عند إنشاء الاتصال. يمكن أن تظهر هذه الرسائل فقط مع BIO من نوع BIO_s_connect() أو BIO_s_accept() على التوالي. لمعرفة متى تم إنشاء الاتصال بنجاح، يمكن على العديد من المنصات استخدام select() أو poll() للكتابة على واصف ملف المقبس.

SSL_ERROR_WANT_X509_LOOKUP

لم تكتمل العملية لأن رد اتصال تطبيق معيَّن بواسطة SSL_CTX_set_client_cert_cb() طلب استدعاءه مرة أخرى. ينبغي استدعاء دالة الإدخال/الإخراج TLS/SSL لاحقًا. تعتمد التفاصيل على التطبيق.

SSL_ERROR_WANT_ASYNC

لم تكتمل العملية لأن محركًا غير متزامن لا يزال يعالج البيانات. سيحدث هذا فقط إذا تم تعيين الوضع إلى SSL_MODE_ASYNC باستخدام SSL_CTX_set_mode(3) أو SSL_set_mode(3) ويُستخدم محرك قادر على المعالجة غير المتزامنة. يمكن للتطبيق تحديد ما إذا كان المحرك قد أكمل معالجته باستخدام select() أو poll() على واصف ملف الانتظار غير المتزامن. يتوفر واصف الملف هذا باستدعاء SSL_get_all_async_fds(3) أو SSL_get_changed_async_fds(3). ينبغي استدعاء دالة الإدخال/الإخراج TLS/SSL لاحقًا. يجب استدعاء الدالة من نفس الخيط الذي صدر منه الاستدعاء الأصلي.

SSL_ERROR_WANT_ASYNC_JOB

تعذر بدء المهمة غير المتزامنة لعدم توفر مهام غير متزامنة في المجموعة (انظر ASYNC_init_thread(3)). سيحدث هذا فقط إذا تم تعيين الوضع إلى SSL_MODE_ASYNC باستخدام SSL_CTX_set_mode(3) أو SSL_set_mode(3) وتم تعيين حد أقصى لمجموعة المهام غير المتزامنة من خلال استدعاء ASYNC_init_thread(3). ينبغي للتطبيق إعادة محاولة العملية بعد اكتمال عملية غير متزامنة قيد التنفيذ حاليًا للخيط الحالي.

SSL_ERROR_WANT_CLIENT_HELLO_CB

لم تكتمل العملية لأن رد اتصال تطبيق معيَّن بواسطة SSL_CTX_set_client_hello_cb() طلب استدعاءه مرة أخرى. ينبغي استدعاء دالة الإدخال/الإخراج TLS/SSL لاحقًا. تعتمد التفاصيل على التطبيق.

SSL_ERROR_SYSCALL

حدث خطأ إدخال/إخراج قاتل غير قابل للاسترداد. قد يحتوي طابور أخطاء OpenSSL على مزيد من المعلومات حول الخطأ. بالنسبة لإدخال/إخراج المقبس على أنظمة Unix، راجع errno للتفاصيل. إذا حدث هذا الخطأ، فلا ينبغي إجراء أي عمليات إدخال/إخراج أخرى على الاتصال ويجب عدم استدعاء SSL_shutdown().

يمكن أيضًا إرجاع هذه القيمة لأخطاء أخرى، تحقق من طابور الأخطاء للتفاصيل.

SSL_ERROR_SSL

حدث خطأ قاتل غير قابل للاسترداد في مكتبة SSL، عادةً خطأ بروتوكول. يحتوي طابور أخطاء OpenSSL على مزيد من المعلومات حول الخطأ. إذا حدث هذا الخطأ، فلا ينبغي إجراء أي عمليات إدخال/إخراج أخرى على الاتصال ويجب عدم استدعاء SSL_shutdown().

يمكن فحص طابور أخطاء OpenSSL باستخدام عائلة دوال ERR، مثل ERR_print_errors(3) و ERR_peek_last_error_all(3).

انظر أيضًا¶

ssl(7)، ERR_clear_error(3)، ERR_print_errors(3)، ERR_peek_last_error_all(3)

التاريخ¶

أُضيف رمز الخطأ SSL_ERROR_WANT_ASYNC في OpenSSL 1.1.0. أُضيف رمز الخطأ SSL_ERROR_WANT_CLIENT_HELLO_CB في OpenSSL 1.1.1.

حقوق النسخ¶

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

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

ترجمة¶

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

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

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