SSL_CTX_SET_PSK_CLIENT_CALLBACK(3SSL)

الاسم
SSL_psk_client_cb_func, SSL_psk_use_session_cb_func, SSL_CTX_set_psk_client_callback, SSL_set_psk_client_callback, SSL_CTX_set_psk_use_session_callback, SSL_set_psk_use_session_callback - ضبط دالة الاستدعاء لعميل PSK

موجز
 #include <openssl/ssl.h>

 typedef int (*SSL_psk_use_session_cb_func)(SSL *ssl, const EVP_MD *md,
                                            const unsigned char **id,
                                            size_t *idlen,
                                            SSL_SESSION **sess);

 void SSL_CTX_set_psk_use_session_callback(SSL_CTX *ctx,
                                           SSL_psk_use_session_cb_func cb);
 void SSL_set_psk_use_session_callback(SSL *s, SSL_psk_use_session_cb_func cb);

 typedef unsigned int (*SSL_psk_client_cb_func)(SSL *ssl,
                                                const char *hint,
                                                char *identity,
                                                unsigned int max_identity_len,
                                                unsigned char *psk,
                                                unsigned int max_psk_len);

 void SSL_CTX_set_psk_client_callback(SSL_CTX *ctx, SSL_psk_client_cb_func cb);
 void SSL_set_psk_client_callback(SSL *ssl, SSL_psk_client_cb_func cb);

الوصف
تطبيق عميل يرغب في استخدام PSKs لـ TLSv1.3 يجب أن يستخدم إما SSL_CTX_set_psk_use_session_callback() أو SSL_set_psk_use_session_callback() حسب المناسبة. لا يمكن استخدام هذه الدوال لـ PSKs الخاصة بـ TLSv1.2 وما دونه.

تُعطى دالة الاستدعاء مؤشرًا لاتصال SSL في ssl.

في المرة الأولى التي تُستدعى فيها دالة الاستدعاء لاتصال، يكون المعامل md هو NULL. في بعض الظروف، تُستدعى دالة الاستدعاء مرة ثانية. في هذه الحالة، يكون الخادم قد حدد مجموعة تشفير لاستخدامها بالفعل، ويجب أن يكون PSK متوافقًا مع الملخص الخاص بتلك المجموعة. يُعطى الملخص في md. يُسمح أن يكون PSK المُعاد من دالة الاستدعاء مختلفًا بين المرة الأولى والثانية التي تُستدعى فيها.

عند الإكمال الناجح، يجب على دالة الاستدعاء تخزين مؤشر لمعرّف PSK في *id. يجب تخزين طول المعرّف بالبايتات في *idlen. تبقى الذاكرة المشار إليها بواسطة *id مملوكة للتطبيق ويجب تحريرها منه حسب الحاجة في أي نقطة بعد اكتمال المصافحة.

بالإضافة إلى ذلك، يجب على دالة الاستدعاء تخزين مؤشر لكائن SSL_SESSION في *sess. يُستخدم هذا كأساس لـ PSK، ويجب، على الأقل، تعيين الحقول التالية:

المفتاح الرئيس
    يمكن تعيين هذا عبر استدعاء SSL_SESSION_set1_master_key(3).

مجموعة تشفير
    فقط ملخص المصافحة المرتبط بمجموعة التشفير هو ذو صلة بـ PSK (قد يستمر الخادم في التفاوض على أي مجموعة تشفير متوافقة مع الملخص). يمكن للتطبيق استخدام أي مجموعة تشفير لـ TLSv1.3. إذا كان md ليس NULL، يجب أن يكون ملخص المصافحة لمجموعة التشفير هو نفسه. يمكن تعيين مجموعة التشفير عبر استدعاء <SSL_SESSION_set_cipher(3)>. يمكن التحقق من ملخص المصافحة لكائن SSL_CIPHER باستخدام <SSL_CIPHER_get_handshake_digest(3)>.

إصدار البروتوكول
    يمكن تعيين هذا عبر استدعاء SSL_SESSION_set_protocol_version(3) ويجب أن يكون TLS1_3_VERSION.

بالإضافة إلى ذلك، يجب تعيين قيمة البيانات المبكرة القصوى عبر استدعاء SSL_SESSION_set_max_early_data(3) إذا كان PSK سيُستخدم لإرسال بيانات مبكرة.

بدلاً من ذلك، يمكن أيضًا استخدام SSL_SESSION تم إنشاؤه من مصافحة سابقة غير PSK كأساس لـ PSK.

تُمرر ملكية كائن SSL_SESSION إلى مكتبة OpenSSL، وبالتالي لا يجب تحريره من التطبيق.

لاحظ أنه كما هو موصوف أعلاه، قد تُستدعى دالة الاستدعاء مرة ثانية أثناء المصافحة. نظرًا لأن ملكية SSL_SESSION تُنقل إلى OpenSSL في كل استدعاء، إذا رغبت دالة الاستدعاء في إرجاع نفس مؤشر SSL_SESSION في استدعاء لاحق، يجب عليها أولاً استدعاء SSL_SESSION_up_ref(3) لزيادة عدد المراجع. عدم القيام بذلك سيؤدي إلى خطأ استخدام بعد التحرير. بدلاً من ذلك، قد تُرجع دالة الاستدعاء كائن SSL_SESSION مختلفًا في كل استدعاء (مثلًا، باستدعاء SSL_SESSION_dup(3)).

من الممكن أيضًا أن تنجح دالة الاستدعاء ولكن لا توفر PSK. في هذه الحالة، لن يُرسل أي PSK إلى الخادم ولكن ستستمر المصافحة. للقيام بذلك، يجب أن تعود دالة الاستدعاء بنجاح وتضمن أن *sess هو NULL. سيتم تجاهل محتويات *id و *idlen.

يجب على تطبيق عميل يرغب في استخدام معميات PSK لـ TLSv1.2 وما دونه توفير دالة رد نداء مختلفة. تُستدعى هذه الدالة عندما يرسل العميل رسالة ClientKeyExchange إلى الخادم.

الغرض من دالة رد النداء هو اختيار هوية PSK والمفتاح المشترك مسبقًا لاستخدامهما خلال مرحلة إعداد الاتصال.

تُضبط دالة رد النداء باستخدام الدالتين SSL_CTX_set_psk_client_callback() أو SSL_set_psk_client_callback(). تُعطى دالة رد النداء الاتصال في المعامل ssl، وتلميح هوية PSK منتهي بـ NUL يُرسله الخادم في المعامل hint، ومخزنًا مؤقتًا identity بطول max_identity_len بايت (بما في ذلك المنهي NUL) حيث تُخزَّن الهوية الناتجة المنتهية بـ NUL، ومخزنًا مؤقتًا psk بطول max_psk_len بايت حيث يُخزَّن المفتاح المشترك مسبقًا الناتج.

ستعمل دالة رد النداء المستخدمة في TLSv1.2 أيضًا في TLSv1.3، على الرغم من أنه يُوصى باستخدام SSL_CTX_set_psk_use_session_callback() أو SSL_set_psk_use_session_callback() لهذا الغرض بدلاً من ذلك. إذا تم التفاوض على TLSv1.3، فسيتحقق OpenSSL أولاً مما إذا كانت دالة رد نداء قد ضُبطت عبر SSL_CTX_set_psk_use_session_callback() أو SSL_set_psk_use_session_callback() وسيستخدمها كأولوية. إذا لم توجد دالة رد نداء من هذا القبيل، فسيتحقق مما إذا كانت دالة رد نداء قد ضُبطت عبر SSL_CTX_set_psk_client_callback() أو SSL_set_psk_client_callback() ويستخدمها. في هذه الحالة، ستكون قيمة hint دائمًا NULL وسيكون ملخص المصافحة مبدئيًا SHA-256 لأي PSK مُعاد. تبادلات البيانات المبكرة لـ TLSv1.3 ممكنة في اتصالات PSK فقط مع دالة رد النداء SSL_psk_use_session_cb_func، وغير ممكنة مع دالة رد النداء SSL_psk_client_cb_func.

ملاحظات
لاحظ أن المعامل hint المُعطى لدالة رد النداء قد يكون NULL.

سيظهر الاتصال المنشأ عبر TLSv1.3 PSK كما لو أن استئناف الجلسة قد حدث بحيث تُعيد SSL_session_reused(3) قيمة «صواب».

لا توجد مشكلات أمنية معروفة عند مشاركة نفس PSK بين TLSv1.2 (أو أقل) و TLSv1.3. ومع ذلك، تحتوي RFC على هذه الملحوظة التحذيرية:

"على الرغم من عدم وجود طريقة معروفة يمكن من خلالها لنفس PSK إنتاج مخرجات مرتبطة في كلا الإصدارين، إلا أنه لم يُجرَ إلا تحليل محدود. يمكن للمنفذين ضمان السلامة من المخرجات المرتبطة عبر البروتوكولات بعدم إعادة استخدام مفاتيح PSK بين TLS 1.3 و TLS 1.2."

القيم المُرجعة
تُفسَّر القيم المُعادة من دالة رد النداء SSL_psk_client_cb_func كالتالي:

عند النجاح (وجدت دالة رد النداء هوية PSK ومفتاحًا مشتركًا مسبقًا لاستخدامه)، يُعاد طول (> 0) psk بالبايت.

وإلا أو عند الأخطاء، يجب أن تُعيد دالة رد النداء 0. في هذه الحالة، يفشل إعداد الاتصال.

يجب أن تُعيد دالة رد النداء SSL_psk_use_session_cb_func القيمة 1 عند النجاح أو 0 عند الفشل. في حالة الفشل، يفشل إعداد الاتصال.

انظر أيضًا
ssl(7), SSL_CTX_set_psk_find_session_callback(3), SSL_set_psk_find_session_callback(3)

التاريخ
أُضيفت SSL_CTX_set_psk_use_session_callback() و SSL_set_psk_use_session_callback() في OpenSSL 1.1.1.

حقوق النسخ
حقوق النشر 2006-2026 لمؤلفي مشروع OpenSSL. جميع الحقوق محفوظة.

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

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

هذه الترجمة هي وثيقة مجانية؛ راجع رخصة جنو العامة الإصدار 3 (https://www.gnu.org/licenses/gpl-3.0.html) أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات.

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