الاسم¶

SSL_read_ex, SSL_read, SSL_peek_ex, SSL_peek - قراءة البايتات من اتصال TLS/SSL

موجز¶

 #include <openssl/ssl.h>
 int SSL_read_ex(SSL *ssl, void *buf, size_t num, size_t *readbytes);
 int SSL_read(SSL *ssl, void *buf, int num);
 int SSL_peek_ex(SSL *ssl, void *buf, size_t num, size_t *readbytes);
 int SSL_peek(SSL *ssl, void *buf, int num);

الوصف¶

تحاول SSL_read_ex() و SSL_read() قراءة num بايت من ssl المحدد إلى المخزن المؤقت buf. عند النجاح، تخزن SSL_read_ex() عدد البايتات المقروءة فعليًا في *readbytes.

SSL_peek_ex() و SSL_peek() مطابقتان لـ SSL_read_ex() و SSL_read() على التوالي، باستثناء أنه لا تُزال أي بايتات فعليًا من BIO الأساسي أثناء القراءة، بحيث يُعيد استدعاء لاحق لـ SSL_read_ex() أو SSL_read() نفس البايتات على الأقل.

ملاحظات¶

في الفقرات أدناه، تُعرف "دالة قراءة" بأنها إحدى SSL_read_ex()، SSL_read()، SSL_peek_ex() أو SSL_peek().

إذا لزم الأمر، تتفاوض دالة القراءة على جلسة TLS/SSL، إذا لم تُجرَ صراحةً بواسطة SSL_connect(3) أو SSL_accept(3). إذا طلب النظير إعادة التفاوض، تُجرى بشفافية أثناء عملية دالة القراءة. يعتمد سلوك دوال القراءة على BIO الأساسي.

لكي تنجح المفاوضة الشفافة، يجب أن يكون ssl قد هُيئ إلى وضع العميل أو الخادم. يُفعل ذلك باستدعاء SSL_set_connect_state(3) أو SSL_set_accept_state() قبل أول استدعاء لدالة قراءة.

تعمل دوال القراءة بناءً على سجلات SSL/TLS. تُستقبل البيانات في سجلات (بحجم أقصى 16 كيلوبايت). فقط عند استلام السجل بالكامل، يمكن معالجته (فك التشفير والتحقق من التكامل). لذلك، يمكن تخزين البيانات التي لم تُسترجع في آخر استدعاء قراءة مؤقتًا داخل طبقة SSL وتُسترجع في استدعاء القراءة التالي. إذا كان num أكبر من عدد البايتات المخزنة مؤقتًا، تعيد دوال القراءة مع البايتات المخزنة. إذا لم تكن هناك بايتات أخرى في المخزن المؤقت، تُحفز دوال القراءة معالجة السجل التالي. فقط عند استلام السجل ومعالجته بالكامل، تعيد دوال القراءة بنجاح. يُعاد محتوى سجل واحد على الأكثر. نظرًا لأن حجم سجل SSL/TLS قد يتجاوز الحجم الأقصى للحزمة للنقل الأساسي (مثل TCP)، قد يكون من الضروري قراءة عدة حزم من طبقة النقل قبل اكتمال السجل ونجاح استدعاء القراءة.

إذا أُطفئ SSL_MODE_AUTO_RETRY وعُولج سجل بيانات غير تطبيقي، يمكن لدالة القراءة أن تعيد وتضبط الخطأ إلى SSL_ERROR_WANT_READ. في هذه الحالة، قد تظل هناك بيانات غير معالجة متاحة في BIO. إذا ضُبط القراءة المسبقة باستخدام SSL_CTX_set_read_ahead(3)، قد تظل هناك أيضًا بيانات غير معالجة متاحة في SSL. يمكن التحكم في هذا السلوك باستخدام استدعاء SSL_CTX_set_mode(3).

إذا كان BIO الأساسي blocking، تعيد دالة القراءة فقط بعد انتهاء عملية القراءة أو حدوث خطأ، باستثناء عندما يُعالج سجل بيانات غير تطبيقي ولا يُضبط SSL_MODE_AUTO_RETRY. لاحظ أنه إذا ضُبط SSL_MODE_AUTO_RETRY وتوفرت بيانات غير تطبيقية فقط، يتعطل الاستدعاء.

إذا كان BIO الأساسي هو غير محظور، فستعود دالة القراءة أيضًا عندما لا يستطيع BIO الأساسي تلبية احتياجات الدالة لمواصلة العملية. في هذه الحالة، سينتج عن استدعاء SSL_get_error(3) بقيمة إرجاع دالة القراءة SSL_ERROR_WANT_READ أو SSL_ERROR_WANT_WRITE. نظرًا لأنه من الممكن في أي وقت إرسال بيانات غير تطبيقية، يمكن لدالة القراءة أيضًا أن تسبب عمليات كتابة. يجب على العملية المستدعية بعد ذلك تكرار الاستدعاء بعد اتخاذ الإجراء المناسب لتلبية احتياجات دالة القراءة. يعتمد الإجراء على BIO الأساسي. عند استخدام مقبس غير محظور، لا يجب فعل شيء، ولكن يمكن استخدام select() للتحقق من الشرط المطلوب. عند استخدام BIO مخبئ، مثل زوج BIO، يجب كتابة البيانات في BIO أو استرجاعها منه قبل القدرة على المتابعة.

يمكن استخدام SSL_pending(3) لمعرفة ما إذا كانت هناك بايتات مخزنة مؤقتًا متاحة للاسترجاع الفوري. في هذه الحالة، يمكن استدعاء دالة القراءة دون حظر أو استقبال بيانات جديدة فعليًا من المقبس الأساسي.

عند استخدامه مع كائن QUIC SSL، يسمح استدعاء دالة إدخال/إخراج مثل SSL_read() بإجراء معالجة أحداث الشبكة الداخلية. من المهم أن تُجرى هذه المعالجة بانتظام. إذا لم يستخدم التطبيق وضع الخيط المساعد، يجب على التطبيق ضمان استدعاء دالة إدخال/إخراج مثل SSL_read() بانتظام، أو بدلاً من ذلك ضمان استدعاء SSL_handle_events() بانتظام. انظر openssl-quic(7) و SSL_handle_events(3) لمزيد من المعلومات.

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

تعيد SSL_read_ex() و SSL_peek_ex() 1 للنجاح أو 0 للفشل. النجاح يعني قراءة بايت واحد أو أكثر من بيانات التطبيق من اتصال SSL. الفشل يعني عدم قراءة أي بايتات من اتصال SSL. يمكن أن تكون حالات الفشل قابلة لإعادة المحاولة (مثل انتظار تسليم المزيد من البايتات بواسطة الشبكة) أو غير قابلة لإعادة المحاولة (مثل خطأ شبكة قاتل). في حالة الفشل، استدع SSL_get_error(3) لمعرفة السبب الذي يشير إلى ما إذا كان الاستدعاء قابلاً لإعادة المحاولة أم لا.

بالنسبة لـ SSL_read() و SSL_peek()، يمكن أن تحدث قيم الإرجاع التالية:

> 0

كانت عملية القراءة ناجحة. قيمة الإرجاع هي عدد البايتات المقروءة فعليًا من اتصال TLS/SSL.

<= 0

لم تنجح عملية القراءة، إما لأن الاتصال أُغلق، أو حدث خطأ، أو يجب اتخاذ إجراء بواسطة العملية المستدعية. استدع SSL_get_error(3) بقيمة الإرجاع ret لمعرفة السبب.

أشارت الوثائق القديمة إلى فرق بين 0 و -1، وأن -1 كان قابلاً لإعادة المحاولة. يجب بدلاً من ذلك استدعاء SSL_get_error() لمعرفة ما إذا كان قابلاً لإعادة المحاولة.

انظر أيضًا¶

SSL_get_error(3), SSL_write_ex(3), SSL_CTX_set_mode(3), SSL_CTX_new(3), SSL_connect(3), SSL_accept(3) SSL_set_connect_state(3), SSL_pending(3), SSL_shutdown(3), SSL_set_shutdown(3), ssl(7), bio(7)

التاريخ¶

أُضيفت الدالتان SSL_read_ex() و SSL_peek_ex() في OpenSSL 1.1.1.

حقوق النسخ¶

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

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

ترجمة¶

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

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

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