الاسم¶

SSL_CTX_set_tlsext_ticket_key_evp_cb, SSL_CTX_set_tlsext_ticket_key_cb - تعيين دالة استدعاء لمعالجة تذاكر الجلسة

موجز¶

 #include <openssl/tls1.h>
 int SSL_CTX_set_tlsext_ticket_key_evp_cb(SSL_CTX sslctx,
     int (*cb)(SSL *s, unsigned char key_name[16],
               unsigned char iv[EVP_MAX_IV_LENGTH],
               EVP_CIPHER_CTX *ctx, EVP_MAC_CTX *hctx, int enc));

الدالة التالية أصبحت مهجورة منذ OpenSSL 3.0، ويمكن إخفاؤها تمامًا عبر تعريف OPENSSL_API_COMPAT بقيمة إصدار مناسبة، انظر openssl_user_macros(7):

 int SSL_CTX_set_tlsext_ticket_key_cb(SSL_CTX sslctx,
     int (*cb)(SSL *s, unsigned char key_name[16],
               unsigned char iv[EVP_MAX_IV_LENGTH],
               EVP_CIPHER_CTX *ctx, HMAC_CTX *hctx, int enc));

الوصف¶

SSL_CTX_set_tlsext_ticket_key_evp_cb() تعيّن دالة استدعاء cb لمعالجة تذاكر الجلسة لسياق SSL sslctx. تذاكر الجلسة، المُعرَّفة في RFC5077، تُوفّر قدرة محسّنة على استئناف الجلسة حيث لا يُطلب من تطبيق الخادم الحفاظ على حالة لكل جلسة. ينطبق هذا فقط على TLS ولا يوجد تطبيق SSLv3.

دالة الاستدعاء cb ستُستدعى لكل جلسة TLS يبدأها العميل عند تقديم امتداد تذكرة الجلسة في رسالة الترحيب TLS. تقع على عاتق هذه الدالة مسؤولية إنشاء أو استرجاع المعاملات التعمية والحفاظ على حالتها.

مكتبة OpenSSL تستخدم دالة الاستدعاء الخاصة بك للمساعدة في تنفيذ حالة بناء تذكرة TLS شائعة وفقًا للقسم 4 من RFC5077 بحيث لا تكون حالة كل جلسة ضرورية وتحتاج مجموعة صغيرة من المتغيرات التعمية إلى الصيانة بواسطة تطبيق دالة الاستدعاء.

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

قبل بدء دالة الاستدعاء، تمت تهيئة ctx و hctx باستخدام EVP_CIPHER_CTX_reset(3) و EVP_MAC_CTX_new(3) على التوالي.

لتذاكر الجلسات الجديدة، عندما لا يقدم العميل تذكرة جلسة، أو فشلت محاولة استرجاع التذكرة، أو أُشير إلى خيار التجديد، ستُستدعى دالة الاستدعاء مع enc مساوية لـ 1. تتوقع مكتبة OpenSSL أن الدالة ستضبط name عشوائياً، وتهيئ iv، وتضبط سياق المُعمِّي ctx وسياق التجزئة hctx.

name طوله 16 حرفًا ويُستخدم كمُعرِّف للمفتاح.

طول iv هو طول IV للمُعمِّي المقابل. الحد الأقصى لطول IV هو EVP_MAX_IV_LENGTH بايت مُعرَّف في <openssl/evp.h>.

متجه التهيئة iv يجب أن يكون قيمة عشوائية. سياق المُعمِّي ctx يجب أن يستخدم متجه التهيئة iv. يمكن تعيين سياق المُعمِّي باستخدام EVP_EncryptInit_ex(3). يمكن تعيين سياق HMAC والملخص باستخدام EVP_MAC_CTX_set_params(3) مع المعاملين OSSL_MAC_PARAM_KEY و OSSL_MAC_PARAM_DIGEST على التوالي.

عندما يقدم العميل تذكرة جلسة، ستُستدعى دالة الاستدعاء مع enc مُعيَّنًا إلى 0 للإشارة إلى أن دالة cb يجب أن تسترجع مجموعة من المعاملات. في هذه الحالة، تم بالفعل تحليل name و iv من تذكرة الجلسة. تتوقع مكتبة OpenSSL أن name سيُستخدم لاسترجاع معاملات تعمية وأن السياق التعمي ctx سيُعيَّن مع المعاملات المسترجعة ومتجه التهيئة iv باستخدام دالة مثل EVP_DecryptInit_ex(3). مادة المفتاح والملخص لـ hctx يحتاجان إلى التعيين باستخدام EVP_MAC_CTX_set_params(3) مع المعاملين OSSL_MAC_PARAM_KEY و OSSL_MAC_PARAM_DIGEST على التوالي.

إذا كان name لا يزال صالحًا ولكن تجديد التذكرة مطلوب، يجب على دالة الاستدعاء إرجاع 2. ستستدعي المكتبة دالة الاستدعاء مرة أخرى مع وسيطة enc مساوية لـ 1 لتعيين التذكرة الجديدة.

قيمة الإرجاع لدالة cb تُستخدم بواسطة OpenSSL لتحديد المعالجة الإضافية التي ستحدث. لقيم الإرجاع التالية معانٍ:

2

يشير هذا إلى أنه تم تعيين ctx و hctx ويمكن للجلسة الاستمرار على تلك المعاملات. بالإضافة إلى ذلك، يشير إلى أن تذكرة الجلسة في فترة تجديد ويجب استبدالها. ستستدعي مكتبة OpenSSL cb مرة أخرى مع وسيطة enc بقيمة 1 لتعيين التذكرة الجديدة (انظر RFC5077 3.3 الفقرة 2).

1

يشير هذا إلى أنه تم تعيين ctx و hctx ويمكن للجلسة الاستمرار على تلك المعاملات.

0

يشير هذا إلى أنه لم يكن من الممكن تعيين/استرجاع تذكرة جلسة وستستمر جلسة SSL/TLS عن طريق التفاوض على مجموعة من المعاملات التعمية أو باستخدام آلية استئناف SSL/TLS البديلة، معرفات الجلسة.

إذا استُدعيت مع enc مساوية لـ 0، ستستدعي المكتبة cb مرة أخرى للحصول على مجموعة جديدة من المعاملات.

أقل من 0

يشير هذا إلى خطأ.

الدالة SSL_CTX_set_tlsext_ticket_key_cb() مطابقة لـ SSL_CTX_set_tlsext_ticket_key_evp_cb() باستثناء أنها تأخذ مؤشر HMAC_CTX مهمل بدلاً من مؤشر EVP_MAC_CTX. قبل بدء دالة الاستدعاء هذه، ستكون hctx قد هُيئت باستخدام EVP_MAC_CTX_new(3) وضُبط الملخص باستخدام EVP_MAC_CTX_set_params(3). يمكن ضبط مادة مفتاح hctx باستخدام HMAC_Init_ex(3).

ملاحظات¶

استئناف الجلسة يختصر المصافحة TLS بحيث لا يحدث تفاوض شهادة العميل. يعوض هذا بتخزين شهادة العميل وجميع معلومات الحالة المتفاوض عليها الأخرى معمّاة داخل التذكرة. في جلسة مستأنفة، ستتوفر للتطبيقات جميع معلومات الحالة هذه تمامًا كما لو حدث تفاوض كامل.

إذا تمكن مهاجم من الحصول على المفتاح المستخدم لتعمية تذكرة جلسة، يمكنه الحصول على السر الرئيسي لأي تذكرة باستخدام ذلك المفتاح وفك تعمية أي حركة مرور باستخدام تلك الجلسة: حتى لو كانت مجموعة المُعمِّي تدعم السرية الأمامية. نتيجة لذلك، قد ترغب التطبيقات في استخدام مفاتيح متعددة وتجنب استخدام مفاتيح طويلة الأجل مخزنة في ملفات.

يمكن للتطبيقات استخدام مفاتيح أطول للحفاظ على مستوى ثابت من الأمان. على سبيل المثال، إذا استخدمت مجموعة المُعمِّي مُعمِّيات 256 بت ولكن فقط مفتاح تذكرة 128 بت، فإن الأمان الكلي هو 128 بت فقط لأن كسر مفتاح التذكرة سيمكن المهاجم من الحصول على مفاتيح الجلسة.

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

تُرجع 1 للإشارة إلى أن دالة الاستدعاء ضُبطت و0 خلاف ذلك.

أمثلة¶

التنفيذ المرجعي:

 SSL_CTX_set_tlsext_ticket_key_evp_cb(SSL, ssl_tlsext_ticket_key_cb);
 ...
 static int ssl_tlsext_ticket_key_cb(SSL *s, unsigned char key_name[16],
                                     unsigned char *iv, EVP_CIPHER_CTX *ctx,
                                     EVP_MAC_CTX *hctx, int enc)
 {
     OSSL_PARAM params[3];
     your_type_t *key; /* something that you need to implement */
     if (enc) { /* create new session */
         if (RAND_bytes(iv, EVP_MAX_IV_LENGTH) <= 0)
             return -1; /* insufficient random */
         key = currentkey(); /* something that you need to implement */
         if (key == NULL) {
             /* current key doesn't exist or isn't valid */
             key = createkey(); /*
                                 * Something that you need to implement.
                                 * createkey needs to initialise a name,
                                 * an aes_key, a hmac_key and optionally
                                 * an expire time.
                                 */
             if (key == NULL) /* key couldn't be created */
                 return 0;
         }
         memcpy(key_name, key->name, 16);
         if (EVP_EncryptInit_ex(&ctx, EVP_aes_256_cbc(), NULL, key->aes_key,
                                iv) == 0)
            return -1; /* error in cipher initialisation */
         params[0] = OSSL_PARAM_construct_octet_string(OSSL_MAC_PARAM_KEY,
                                                       key->hmac_key, 32);
         params[1] = OSSL_PARAM_construct_utf8_string(OSSL_MAC_PARAM_DIGEST,
                                                      "sha256", 0);
         params[2] = OSSL_PARAM_construct_end();
         if (EVP_MAC_CTX_set_params(hctx, params) == 0)
            return -1; /* error in mac initialisation */
         return 1;
     } else { /* retrieve session */
         time_t t = time(NULL);
         key = findkey(key_name); /* something that you need to implement */
         if (key == NULL || key->expire < t)
             return 0;
         params[0] = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY,
                                                       key->hmac_key, 32);
         params[1] = OSSL_PARAM_construct_utf8_string(OSSL_MAC_PARAM_DIGEST,
                                                      "sha256", 0);
         params[2] = OSSL_PARAM_construct_end();
         if (EVP_MAC_CTX_set_params(hctx, params) == 0)
            return -1; /* error in mac initialisation */
         if (EVP_DecryptInit_ex(&ctx, EVP_aes_256_cbc(), NULL, key->aes_key,
                                iv) == 0)
            return -1; /* error in cipher initialisation */
         if (key->expire < t - RENEW_TIME) { /* RENEW_TIME: implement */
             /*
              * return 2 - This session will get a new ticket even though the
              * current one is still valid.
              */
             return 2;
         }
         return 1;
     }
 }

انظر أيضًا¶

ssl(7), SSL_set_session(3), SSL_session_reused(3), SSL_CTX_add_session(3), SSL_CTX_sess_number(3), SSL_CTX_sess_set_get_cb(3), SSL_CTX_set_session_id_context(3),

التاريخ¶

الدالة SSL_CTX_set_tlsext_ticket_key_cb() أُهملت في OpenSSL 3.0.

الدالة SSL_CTX_set_tlsext_ticket_key_evp_cb() قُدمت في OpenSSL 3.0.

حقوق النسخ¶

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

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

ترجمة¶

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

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

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