الاسم¶

BIO_do_handshake, BIO_f_ssl, BIO_set_ssl, BIO_get_ssl, BIO_set_ssl_mode, BIO_set_ssl_renegotiate_bytes, BIO_get_num_renegotiates, BIO_set_ssl_renegotiate_timeout, BIO_new_ssl, BIO_new_ssl_connect, BIO_new_buffer_ssl_connect, BIO_ssl_copy_session_id, BIO_ssl_shutdown - SSL BIO

موجز¶

 #include <openssl/bio.h>
 #include <openssl/ssl.h>
 const BIO_METHOD *BIO_f_ssl(void);
 long BIO_set_ssl(BIO *b, SSL *ssl, long c);
 long BIO_get_ssl(BIO *b, SSL **sslp);
 long BIO_set_ssl_mode(BIO *b, long client);
 long BIO_set_ssl_renegotiate_bytes(BIO *b, long num);
 long BIO_set_ssl_renegotiate_timeout(BIO *b, long seconds);
 long BIO_get_num_renegotiates(BIO *b);
 BIO *BIO_new_ssl(SSL_CTX *ctx, int client);
 BIO *BIO_new_ssl_connect(SSL_CTX *ctx);
 BIO *BIO_new_buffer_ssl_connect(SSL_CTX *ctx);
 int BIO_ssl_copy_session_id(BIO *to, BIO *from);
 void BIO_ssl_shutdown(BIO *bio);
 long BIO_do_handshake(BIO *b);

الوصف¶

BIO_f_ssl() تُرجع طريقة SSL BIO. هذه BIO مرشحة وهي غلاف حول روتينات OpenSSL SSL تُضيف "نكهة" BIO إلى إدخال/إخراج SSL.

الإدخال/الإخراج المُنفَّذ على SSL BIO يتواصل باستخدام بروتوكول SSL مع BIOs القراءة والكتابة الخاصة بـ SSL. إذا لم يُؤسَّس اتصال SSL، يُبذل جهد لتأسيسه عند أول استدعاء إدخال/إخراج.

إذا أُلحقت BIO بـ SSL BIO باستخدام BIO_push()، تُستخدم آليًا كـ BIOs القراءة والكتابة الخاصة بـ SSL BIO.

استدعاء BIO_reset() على SSL BIO يُغلق أي اتصال SSL حالي باستدعاء SSL_shutdown(). ثم يُرسل BIO_reset() إلى BIO التالية في السلسلة: هذا عادةً يفصل النقل الأساسي. ثم يُعاد تعيين SSL BIO إلى حالة القبول أو الاتصال الأولية.

إذا ضُبط علم الإغلاق عند تحرير SSL BIO، يُحرر أيضًا الهيكل الداخلي SSL باستخدام SSL_free().

BIO_set_ssl() يضبط المؤشر الداخلي SSL لـ SSL BIO b إلى ssl باستخدام علم الإغلاق c.

BIO_get_ssl() يسترجع المؤشر SSL لـ SSL BIO b، ثم يمكن التلاعب به باستخدام دوال مكتبة SSL القياسية.

BIO_set_ssl_mode() يضبط وضع SSL BIO إلى client. إذا كان client هو 1، يُضبط وضع العميل. إذا كان client هو 0، يُضبط وضع الخادم.

BIO_set_ssl_renegotiate_bytes() يضبط عدد بايتات إعادة التفاوض لـ SSL BIO b إلى num. عند الضبط، بعد كل num بايت من الإدخال/الإخراج (قراءة وكتابة)، يُعاد التفاوض على جلسة SSL آليًا. يجب أن يكون num على الأقل 512 بايت.

BIO_set_ssl_renegotiate_timeout() يضبط مهلة إعادة التفاوض لـ SSL BIO b إلى seconds. عندما تنقضي مهلة إعادة التفاوض، يُعاد التفاوض على الجلسة آليًا.

BIO_get_num_renegotiates() تُرجع العدد الإجمالي لإعادة تفاوض الجلسة بسبب الإدخال/الإخراج أو المهلة لـ SSL BIO b.

BIO_new_ssl() يخصص SSL BIO باستخدام SSL_CTX ctx وباستخدام وضع العميل إذا كان client غير صفري.

BIO_new_ssl_connect() ينشئ سلسلة BIO جديدة تتكون من SSL BIO (باستخدام ctx) متبوعة بـ BIO اتصال.

BIO_new_buffer_ssl_connect() ينشئ سلسلة BIO جديدة تتكون من BIO تخزين مؤقت، وSSL BIO (باستخدام ctx)، وBIO اتصال.

BIO_ssl_copy_session_id() تنسخ مُعرّف جلسة SSL بين سلسلتي BIO from و to. تفعل ذلك بتحديد BIOs SSL في كل سلسلة واستدعاء SSL_copy_session_id() على مؤشر SSL الداخلي.

BIO_ssl_shutdown() تغلق اتصال SSL على سلسلة BIO bio. تفعل ذلك بتحديد SSL BIO في السلسلة واستدعاء SSL_shutdown() على مؤشر SSL الداخلي.

BIO_do_handshake() تحاول إكمال مصافحة SSL على BIO المُقدّم وإنشاء اتصال SSL. بالنسبة لـ BIOs غير SSL، يُجرى الاتصال عادةً على مستوى TCP. إذا أسفر تحليل اسم النطاق عن عناوين IP متعددة، تُجرى محاولة جميعها بعد فشل connect(). تُعيد الدالة 1 إذا أُنشئ الاتصال بنجاح. تُعاد قيمة صفرية أو سالبة إذا تعذر إنشاء الاتصال. يجب استخدام الاستدعاء BIO_should_retry() لـ BIOs الاتصال غير المحظورة لتحديد ما إذا كان يجب إعادة محاولة الاستدعاء. إذا أُنشئ اتصال بالفعل، فلا تأثير لهذا الاستدعاء.

ملاحظات¶

BIOs SSL استثنائية حيث إذا كان النقل الأساسي غير محظور، فلا يزال بإمكانها طلب إعادة محاولة في ظروف استثنائية. تحديدًا، سيحدث هذا إذا جرت إعادة تفاوض على الجلسة أثناء عملية BIO_read_ex()، ومن الحالات التي يحدث فيها ذلك عند حدوث تصعيد.

يمكن تعيين علامة SSL_AUTO_RETRY لتعطيل هذا السلوك. أي عند تعيين هذه العلامة، لن يطلب SSL BIO الذي يستخدم نقلًا محظورًا إعادة محاولة أبدًا.

بما أن عمليات BIO_ctrl() غير المعروفة تُرسل عبر BIOs التصفية، يمكن تعيين اسم الخادم والمنفذ باستخدام BIO_set_host() على BIO المُعاد بواسطة BIO_new_ssl_connect() دون الحاجة إلى تحديد BIO الاتصال أولاً.

لا يتعين على التطبيقات استدعاء BIO_do_handshake() ولكن قد ترغب في فعل ذلك لفصل عملية المصافحة عن معالجة الإدخال/الإخراج الأخرى.

BIO_set_ssl() و BIO_get_ssl() و BIO_set_ssl_mode() و BIO_set_ssl_renegotiate_bytes() و BIO_set_ssl_renegotiate_timeout() و BIO_get_num_renegotiates() و BIO_do_handshake() مُنفّذة كوحدات ماكرو.

BIO_ssl_copy_session_id() غير مدعومة حاليًا على كائنات QUIC SSL وتفشل إذا استُدعيت على مثل هذا الكائن.

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

BIO_f_ssl() تُعيد بنية BIO_METHOD الخاصة بـ SSL.

BIO_set_ssl() و BIO_get_ssl() و BIO_set_ssl_mode() و BIO_set_ssl_renegotiate_bytes() و BIO_set_ssl_renegotiate_timeout() و BIO_get_num_renegotiates() تُعيد 1 عند النجاح أو قيمة أقل من أو تساوي 0 إذا حدث خطأ.

BIO_new_ssl() و BIO_new_ssl_connect() و BIO_new_buffer_ssl_connect() تُعيد بنية BIO صالحة عند النجاح أو NULL إذا حدث خطأ.

BIO_ssl_copy_session_id() تُعيد 1 عند النجاح أو 0 عند الخطأ، أو إذا استُدعيت على كائن QUIC SSL.

BIO_do_handshake() تُعيد 1 إذا أُنشئ الاتصال بنجاح. تُعاد قيمة صفرية أو سالبة إذا تعذر إنشاء الاتصال.

أمثلة¶

يحاول مثال عميل SSL/TLS هذا استرداد صفحة من خادم ويب SSL/TLS. إجراءات الإدخال/الإخراج مطابقة لتلك الموجودة في المثال غير المُعمّى في BIO_s_connect(3).

 BIO *sbio, *out;
 int len;
 char tmpbuf[1024];
 SSL_CTX *ctx;
 SSL *ssl;
 /* XXX Seed the PRNG if needed. */
 ctx = SSL_CTX_new(TLS_client_method());
 /* XXX Set verify paths and mode here. */
 sbio = BIO_new_ssl_connect(ctx);
 BIO_get_ssl(sbio, &ssl);
 if (ssl == NULL) {
     fprintf(stderr, "Can't locate SSL pointer\n");
     ERR_print_errors_fp(stderr);
     exit(1);
 }
 /* XXX We might want to do other things with ssl here */
 /* An empty host part means the loopback address */
 BIO_set_conn_hostname(sbio, ":https");
 out = BIO_new_fp(stdout, BIO_NOCLOSE);
 if (BIO_do_connect(sbio) <= 0) {
     fprintf(stderr, "Error connecting to server\n");
     ERR_print_errors_fp(stderr);
     exit(1);
 }
 /* XXX Could examine ssl here to get connection info */
 BIO_puts(sbio, "GET / HTTP/1.0\n\n");
 for (;;) {
     len = BIO_read(sbio, tmpbuf, 1024);
     if (len <= 0)
         break;
     BIO_write(out, tmpbuf, len);
 }
 BIO_free_all(sbio);
 BIO_free(out);

هذا مثال بسيط لخادم. يستخدم BIO تخزين مؤقت للسماح بقراءة الأسطر من SSL BIO باستخدام BIO_gets. يُنشئ صفحة ويب زائفة تحتوي على الطلب الفعلي من عميل ويعيد أيضًا إرسال الطلب إلى الإخراج القياسي.

 BIO *sbio, *bbio, *acpt, *out;
 int len;
 char tmpbuf[1024];
 SSL_CTX *ctx;
 SSL *ssl;
 /* XXX Seed the PRNG if needed. */
 ctx = SSL_CTX_new(TLS_server_method());
 if (!SSL_CTX_use_certificate_file(ctx, "server.pem", SSL_FILETYPE_PEM)
         || !SSL_CTX_use_PrivateKey_file(ctx, "server.pem", SSL_FILETYPE_PEM)
         || !SSL_CTX_check_private_key(ctx)) {
     fprintf(stderr, "Error setting up SSL_CTX\n");
     ERR_print_errors_fp(stderr);
     exit(1);
 }
 /* XXX Other things like set verify locations, EDH temp callbacks. */
 /* New SSL BIO setup as server */
 sbio = BIO_new_ssl(ctx, 0);
 BIO_get_ssl(sbio, &ssl);
 if (ssl == NULL) {
     fprintf(stderr, "Can't locate SSL pointer\n");
     ERR_print_errors_fp(stderr);
     exit(1);
 }
 bbio = BIO_new(BIO_f_buffer());
 sbio = BIO_push(bbio, sbio);
 acpt = BIO_new_accept("4433");
 /*
  * By doing this when a new connection is established
  * we automatically have sbio inserted into it. The
  * BIO chain is now 'swallowed' by the accept BIO and
  * will be freed when the accept BIO is freed.
  */
 BIO_set_accept_bios(acpt, sbio);
 out = BIO_new_fp(stdout, BIO_NOCLOSE);
 /* First call to BIO_do_accept() sets up accept BIO */
 if (BIO_do_accept(acpt) <= 0) {
     fprintf(stderr, "Error setting up accept BIO\n");
     ERR_print_errors_fp(stderr);
     exit(1);
 }

/* Second call to BIO_do_accept() waits for incoming connection */
if (BIO_do_accept(acpt) <= 0) {
fprintf(stderr, "Error accepting connection\n");
ERR_print_errors_fp(stderr);
exit(1);
}

 /* We only want one connection so remove and free accept BIO */
 sbio = BIO_pop(acpt);
 BIO_free_all(acpt);
 if (BIO_do_handshake(sbio) <= 0) {
     fprintf(stderr, "Error in SSL handshake\n");
     ERR_print_errors_fp(stderr);
     exit(1);
 }
 BIO_puts(sbio, "HTTP/1.0 200 OK\r\nContent-type: text/plain\r\n\r\n");
 BIO_puts(sbio, "\r\nConnection Established\r\nRequest headers:\r\n");
 BIO_puts(sbio, "--------------------------------------------------\r\n");
 for (;;) {
     len = BIO_gets(sbio, tmpbuf, 1024);
     if (len <= 0)
         break;
     BIO_write(sbio, tmpbuf, len);
     BIO_write(out, tmpbuf, len);
     /* Look for blank line signifying end of headers*/
     if (tmpbuf[0] == '\r' || tmpbuf[0] == '\n')
         break;
 }
 BIO_puts(sbio, "--------------------------------------------------\r\n");
 BIO_puts(sbio, "\r\n");
 BIO_flush(sbio);
 BIO_free_all(sbio);

التاريخ¶

في OpenSSL قبل 1.0.0، عُولجت استدعاء BIO_pop() بشكل غير صحيح، زيد عدد مراجع I/O BIO بشكل غير صحيح (بدلاً من إنقاصه) وفُصل عن SSL BIO حتى لو لم يُفصل SSL BIO صراحة (مثل فصل أعلى السلسلة). يجب تعديل التطبيقات التي تضمنت حلولاً بديلة لهذا الخلل (مثل تحرير BIOs أكثر من مرة) لمعالجة هذا الإصلاح أو قد تحرر BIO محرر بالفعل.

حقوق النسخ¶

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

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

ترجمة¶

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

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

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