الاسم¶

SSL_CTX_set_msg_callback, SSL_CTX_set_msg_callback_arg, SSL_set_msg_callback, SSL_set_msg_callback_arg, SSL_trace - تثبيت دالة رد لمراقبة رسائل البروتوكول

موجز¶

 #include <openssl/ssl.h>
 void SSL_CTX_set_msg_callback(SSL_CTX *ctx,
                               void (*cb)(int write_p, int version,
                                          int content_type, const void *buf,
                                          size_t len, SSL *ssl, void *arg));
 void SSL_CTX_set_msg_callback_arg(SSL_CTX *ctx, void *arg);
 void SSL_set_msg_callback(SSL *ssl,
                           void (*cb)(int write_p, int version,
                                      int content_type, const void *buf,
                                      size_t len, SSL *ssl, void *arg));
 void SSL_set_msg_callback_arg(SSL *ssl, void *arg);
 void SSL_trace(int write_p, int version, int content_type,
                const void *buf, size_t len, SSL *ssl, void *arg);

الوصف¶

يمكن استخدام SSL_CTX_set_msg_callback() أو SSL_set_msg_callback() لتعريف دالة رد رسائل cb لمراقبة جميع رسائل بروتوكول SSL/TLS/QUIC (مثل رسائل المصافحة) التي تُستقبل أو تُرسل، بالإضافة إلى أحداث أخرى تحدث أثناء المعالجة. ويمكن استخدام SSL_CTX_set_msg_callback_arg() و SSL_set_msg_callback_arg() لتعيين المعامل arg لدالة الرد، وهو متاح للاستخدام التطبيقي التعسفي.

تحدد SSL_CTX_set_msg_callback() و SSL_CTX_set_msg_callback_arg() إعدادات مبدئية تُنسخ إلى كائنات SSL جديدة بواسطة SSL_new(3). وتعدل SSL_set_msg_callback() و SSL_set_msg_callback_arg() الإعدادات الفعلية لكائن SSL. استخدام مؤشر NULL لـ cb يُعطل دالة رد الرسائل.

عندما تُستدعى cb بواسطة مكتبة SSL/TLS/QUIC، فإن معاملات الدالة تحمل المعاني التالية:

write_p

هذه العلامة تكون 0 عندما تُستقبل رسالة بروتوكول و 1 عندما تُرسل رسالة بروتوكول.

الإصدار

إصدار البروتوكول الذي يُفسر بموجبه رسالة البروتوكول بواسطة المكتبة مثل TLS1_3_VERSION، TLS1_2_VERSION، OSSL_QUIC1_VERSION إلخ. بالنسبة لنوع المحتوى الزائف SSL3_RT_HEADER (انظر الملاحظات أدناه) ستكون هذه القيمة هي حقل الإصدار/الإصدار القديم المُفكك لرأس السجل.

content_type

هذه إحدى قيم أنواع المحتوى المُعرَّفة في مواصفات البروتوكول (SSL3_RT_CHANGE_CIPHER_SPEC، SSL3_RT_ALERT، SSL3_RT_HANDSHAKE؛ ولكن أبدًا SSL3_RT_APPLICATION_DATA لأن دالة الرد تُستدعى فقط لرسائل البروتوكول). بدلاً من ذلك، قد تكون نوع محتوى "زائف". تُستخدم أنواع المحتوى الزائفة هذه للإشارة إلى حدث آخر في معالجة البيانات (انظر الملاحظات أدناه).

buf, len

يشير buf إلى مخزن مؤقت يحتوي على رسالة البروتوكول أو بيانات أخرى (في حالة أنواع المحتوى الزائفة)، والذي يتكون من len بايت. لم يعد المخزن المؤقت صالحًا بعد عودة دالة الرد.

ssl

كائن SSL الذي استقبل أو أرسل الرسالة.

الوسيط

الوسيط المُعرَّف من قِبل المستخدم، والذي يُعرَّف اختياريًا بواسطةSSL_CTX_set_msg_callback_arg() أو SSL_set_msg_callback_arg().

يمكن استخدام الدالة SSL_trace() كدالة رد نداء مُعدة مسبقًا في استدعاءإلى SSL_CTX_set_msg_callback() أو SSL_set_msg_callback().يتطلب ذلك تعيين BIO كوسيط رد نداء عبرSSL_CTX_set_msg_callback_arg() أو SSL_set_msg_callback_arg().سيؤدي تعيين دالة رد النداء هذه إلى كتابة معلومات تتبع تشخيصية قابلة للقراءة البشريةحول اتصال SSL/TLS/QUIC إلى BIO.

ملاحظات¶

تُمرَّر رسائل البروتوكول إلى دالة الاستدعاء بعد فك التعمية وتجميع الأجزاء حيثما ينطبق ذلك. (وبالتالي، لا تكون حدود السجلات مرئية.)

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

بسبب التفاوض الآلي على إصدار البروتوكول، فإن version ليس بالضرورة إصدار البروتوكول المستخدم من قبل مرسل الرسالة: إذا تم استقبال رسالة TLS 1.0 ClientHello بواسطة خادم SSL 3.0 فقط، فسيكون version هو SSL3_VERSION.

قد تُرسل قيم أنواع محتوى زائفة في نقاط مختلفة أثناء معالجة البيانات. أنواع المحتوى الزائفة التالية مُعرَّفة حاليًا:

SSL3_RT_HEADER

يُستخدم عند إرسال أو استقبال سجل TLS. يحتوي buf على بايتات رأس السجل فقط.

SSL3_RT_INNER_CONTENT_TYPE

يُستخدم عند إرسال أو استقبال سجل TLSv1.3 معمّى. في سجلات TLSv1.3 المعمّاة، يكون نوع المحتوى في رأس السجل دائمًا SSL3_RT_APPLICATION_DATA. نوع المحتوى الحقيقي للسجل موجود في نوع محتوى "داخلي". يحتوي buf على بايت نوع المحتوى "الداخلي" المُرمَّز.

SSL3_RT_QUIC_DATAGRAM

يُستخدم عند إرسال أو استقرار رسم بيانات QUIC.

SSL3_RT_QUIC_PACKET

يُستخدم عند إرسال أو استقبال حزمة QUIC.

SSL3_RT_QUIC_FRAME_FULL

يُستخدم عند إرسال أو استقبال إطار QUIC. يُستخدم هذا فقط للإطارات غير المُعمّاة والمرتبطة ببيانات التدفق. يتم توفير بيانات إطار QUIC الكاملة.

SSL3_RT_QUIC_FRAME_HEADER

يُستخدم عند إرسال أو استقبال بيانات تدفق QUIC أو إطار مُعمّى. يتم توفير بيانات رأس إطار QUIC فقط.

SSL3_RT_QUIC_FRAME_PADDING

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

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

لا تُرجع الدوال SSL_CTX_set_msg_callback() و SSL_CTX_set_msg_callback_arg() و SSL_set_msg_callback() و SSL_set_msg_callback_arg() أي قيم.

انظر أيضًا¶

ssl(7)، SSL_new(3)

التاريخ¶

أُضيف نوع المحتوى الزائف SSL3_RT_INNER_CONTENT_TYPE في OpenSSL 1.1.1.

أُضيفت أنواع المحتوى الزائفة SSL3_RT_QUIC_DATAGRAM و SSL3_RT_QUIC_PACKET و SSL3_RT_QUIC_FRAME_FULL و SSL3_RT_QUIC_FRAME_HEADER و SSL3_RT_QUIC_FRAME_PADDING في OpenSSL 3.2.

في الإصدارات السابقة لـ OpenSSL 3.0، استُدعيت cb بالقيمة 0 كـ version لنوع المحتوى الزائف SSL3_RT_HEADER لسجلات TLS.

في الإصدارات السابقة لـ OpenSSL 3.2، استُدعيت cb بالقيمة 0 كـ version لنوع المحتوى الزائف SSL3_RT_HEADER لسجلات DTLS.

حقوق النسخ¶

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

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

ترجمة¶

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

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

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