.\" -*- coding: UTF-8 -*-
.de  Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de  Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de  Ve \" End verbatim text
.ft R
.fi
..
.ie  n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie  \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.de  IX
..
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.nr rF 0
.if  \n(.g .if rF .nr rF 1
.if  (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.if  n .ds AD l
.\"
.\" Required to disable full justification in groff 1.23.0.
.\" ========================================================================
.\"
.IX Title "BIO_F_SSL 3ssl"
.\"*******************************************************************
.\"
.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
.TH BIO_F_SSL 3ssl "7 أبريل 2026" 3.6.2 OpenSSL
.if  n .ad l
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.nh
.SH الاسم
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
.SH موجز
.IX Header موجز
.Vb 2
\& #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);
.Ve
.SH الوصف
.IX Header الوصف
\&\fBBIO_f_ssl()\fP تُرجع طريقة SSL BIO. هذه BIO مرشحة وهي غلاف حول روتينات
OpenSSL SSL تُضيف "نكهة" BIO إلى إدخال/إخراج SSL.
.PP
الإدخال/الإخراج المُنفَّذ على SSL BIO يتواصل باستخدام بروتوكول SSL مع BIOs
القراءة والكتابة الخاصة بـ SSL. إذا لم يُؤسَّس اتصال SSL، يُبذل جهد لتأسيسه
عند أول استدعاء إدخال/إخراج.
.PP
إذا أُلحقت BIO بـ SSL BIO باستخدام \fBBIO_push()\fP، تُستخدم آليًا كـ BIOs
القراءة والكتابة الخاصة بـ SSL BIO.
.PP
استدعاء \fBBIO_reset()\fP على SSL BIO يُغلق أي اتصال SSL حالي باستدعاء
\fBSSL_shutdown()\fP. ثم يُرسل \fBBIO_reset()\fP إلى BIO التالية في السلسلة: هذا
عادةً يفصل النقل الأساسي. ثم يُعاد تعيين SSL BIO إلى حالة القبول أو الاتصال
الأولية.
.PP
إذا ضُبط علم الإغلاق عند تحرير SSL BIO، يُحرر أيضًا الهيكل الداخلي SSL
باستخدام \fBSSL_free()\fP.
.PP
\&\fBBIO_set_ssl()\fP يضبط المؤشر الداخلي SSL لـ SSL BIO \fBb\fP إلى \fBssl\fP
باستخدام علم الإغلاق \fBc\fP.
.PP
\&\fBBIO_get_ssl()\fP يسترجع المؤشر SSL لـ SSL BIO \fBb\fP، ثم يمكن التلاعب به
باستخدام دوال مكتبة SSL القياسية.
.PP
\&\fBBIO_set_ssl_mode()\fP يضبط وضع SSL BIO إلى \fBclient\fP. إذا كان \fBclient\fP هو
1، يُضبط وضع العميل. إذا كان \fBclient\fP هو 0، يُضبط وضع الخادم.
.PP
\&\fBBIO_set_ssl_renegotiate_bytes()\fP يضبط عدد بايتات إعادة التفاوض لـ SSL
BIO \fBb\fP إلى \fBnum\fP. عند الضبط، بعد كل \fBnum\fP بايت من الإدخال/الإخراج (قراءة
وكتابة)، يُعاد التفاوض على جلسة SSL آليًا. يجب أن يكون \fBnum\fP على الأقل 512
بايت.
.PP
\&\fBBIO_set_ssl_renegotiate_timeout()\fP يضبط مهلة إعادة التفاوض لـ SSL BIO
\fBb\fP إلى \fBseconds\fP. عندما تنقضي مهلة إعادة التفاوض، يُعاد التفاوض على
الجلسة آليًا.
.PP
\&\fBBIO_get_num_renegotiates()\fP تُرجع العدد الإجمالي لإعادة تفاوض الجلسة
بسبب الإدخال/الإخراج أو المهلة لـ SSL BIO \fBb\fP.
.PP
\&\fBBIO_new_ssl()\fP يخصص SSL BIO باستخدام SSL_CTX \fBctx\fP وباستخدام وضع العميل
إذا كان \fBclient\fP غير صفري.
.PP
\&\fBBIO_new_ssl_connect()\fP ينشئ سلسلة BIO جديدة تتكون من SSL BIO (باستخدام
\fBctx\fP) متبوعة بـ BIO اتصال.
.PP
\&\fBBIO_new_buffer_ssl_connect()\fP ينشئ سلسلة BIO جديدة تتكون من BIO تخزين
مؤقت، وSSL BIO (باستخدام \fBctx\fP)، وBIO اتصال.
.PP
\&\fBBIO_ssl_copy_session_id()\fP تنسخ مُعرّف جلسة SSL بين سلسلتي BIO \fBfrom\fP و
\fBto\fP. تفعل ذلك بتحديد BIOs SSL في كل سلسلة واستدعاء
\fBSSL_copy_session_id()\fP على مؤشر SSL الداخلي.
.PP
\&\fBBIO_ssl_shutdown()\fP تغلق اتصال SSL على سلسلة BIO \fBbio\fP. تفعل ذلك بتحديد
SSL BIO في السلسلة واستدعاء \fBSSL_shutdown()\fP على مؤشر SSL الداخلي.
.PP
\&\fBBIO_do_handshake()\fP تحاول إكمال مصافحة SSL على BIO المُقدّم وإنشاء اتصال
SSL. بالنسبة لـ BIOs غير SSL، يُجرى الاتصال عادةً على مستوى TCP. إذا أسفر
تحليل اسم النطاق عن عناوين IP متعددة، تُجرى محاولة جميعها بعد فشل
\fBconnect()\fP. تُعيد الدالة 1 إذا أُنشئ الاتصال بنجاح. تُعاد قيمة صفرية أو
سالبة إذا تعذر إنشاء الاتصال. يجب استخدام الاستدعاء \fBBIO_should_retry()\fP لـ
BIOs الاتصال غير المحظورة لتحديد ما إذا كان يجب إعادة محاولة الاستدعاء. إذا
أُنشئ اتصال بالفعل، فلا تأثير لهذا الاستدعاء.
.SH ملاحظات
.IX Header ملاحظات
BIOs SSL استثنائية حيث إذا كان النقل الأساسي غير محظور، فلا يزال بإمكانها
طلب إعادة محاولة في ظروف استثنائية. تحديدًا، سيحدث هذا إذا جرت إعادة تفاوض
على الجلسة أثناء عملية \fBBIO_read_ex()\fP، ومن الحالات التي يحدث فيها ذلك عند
حدوث تصعيد.
.PP
يمكن تعيين علامة SSL_AUTO_RETRY لتعطيل هذا السلوك. أي عند تعيين هذه العلامة،
لن يطلب SSL BIO الذي يستخدم نقلًا محظورًا إعادة محاولة أبدًا.
.PP
بما أن عمليات \fBBIO_ctrl()\fP غير المعروفة تُرسل عبر BIOs التصفية، يمكن تعيين
اسم الخادم والمنفذ باستخدام \fBBIO_set_host()\fP على BIO المُعاد بواسطة
\fBBIO_new_ssl_connect()\fP دون الحاجة إلى تحديد BIO الاتصال أولاً.
.PP
لا يتعين على التطبيقات استدعاء \fBBIO_do_handshake()\fP ولكن قد ترغب في فعل ذلك
لفصل عملية المصافحة عن معالجة الإدخال/الإخراج الأخرى.
.PP
\&\fBBIO_set_ssl()\fP و \fBBIO_get_ssl()\fP و \fBBIO_set_ssl_mode()\fP و
\&\fBBIO_set_ssl_renegotiate_bytes()\fP و \fBBIO_set_ssl_renegotiate_timeout()\fP
و \&\fBBIO_get_num_renegotiates()\fP و \fBBIO_do_handshake()\fP مُنفّذة كوحدات
ماكرو.
.PP
\&\fBBIO_ssl_copy_session_id()\fP غير مدعومة حاليًا على كائنات QUIC SSL وتفشل
إذا استُدعيت على مثل هذا الكائن.
.SH "القيم المُرجعة"
.IX Header "القيم المُرجعة"
\&\fBBIO_f_ssl()\fP تُعيد بنية \fBBIO_METHOD\fP الخاصة بـ SSL.
.PP
\&\fBBIO_set_ssl()\fP و \fBBIO_get_ssl()\fP و \fBBIO_set_ssl_mode()\fP و
\fBBIO_set_ssl_renegotiate_bytes()\fP و \&\fBBIO_set_ssl_renegotiate_timeout()\fP
و \fBBIO_get_num_renegotiates()\fP تُعيد 1 عند النجاح أو قيمة أقل من أو تساوي 0
إذا حدث خطأ.
.PP
\&\fBBIO_new_ssl()\fP و \fBBIO_new_ssl_connect()\fP و
\fBBIO_new_buffer_ssl_connect()\fP تُعيد بنية \fBBIO\fP صالحة عند النجاح أو
\fBNULL\fP إذا حدث خطأ.
.PP
\&\fBBIO_ssl_copy_session_id()\fP تُعيد 1 عند النجاح أو 0 عند الخطأ، أو إذا
استُدعيت على كائن QUIC SSL.
.PP
\&\fBBIO_do_handshake()\fP تُعيد 1 إذا أُنشئ الاتصال بنجاح. تُعاد قيمة صفرية أو
سالبة إذا تعذر إنشاء الاتصال.
.SH أمثلة
.IX Header أمثلة
يحاول مثال عميل SSL/TLS هذا استرداد صفحة من خادم ويب SSL/TLS. إجراءات
الإدخال/الإخراج مطابقة لتلك الموجودة في المثال غير المُعمّى في
\fBBIO_s_connect\fP\|(3).
.PP
.Vb 5
\& 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\*(Aqt locate SSL pointer\en");
\&     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\en");
\&     ERR_print_errors_fp(stderr);
\&     exit(1);
\& }
\&
\& /* XXX Could examine ssl here to get connection info */
\&
\& BIO_puts(sbio, "GET / HTTP/1.0\en\en");
\& for (;;) {
\&     len = BIO_read(sbio, tmpbuf, 1024);
\&     if (len <= 0)
\&         break;
\&     BIO_write(out, tmpbuf, len);
\& }
\& BIO_free_all(sbio);
\& BIO_free(out);
.Ve
.PP
هذا مثال بسيط لخادم. يستخدم BIO تخزين مؤقت للسماح بقراءة الأسطر من SSL BIO
باستخدام BIO_gets. يُنشئ صفحة ويب زائفة تحتوي على الطلب الفعلي من عميل ويعيد
أيضًا إرسال الطلب إلى الإخراج القياسي.
.PP
.Vb 5
\& 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\en");
\&     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\*(Aqt locate SSL pointer\en");
\&     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 \*(Aqswallowed\*(Aq 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\en");
\&     ERR_print_errors_fp(stderr);
\&     exit(1);
\& }
.Ve
.PP
/* Second call to \fBBIO_do_accept()\fP waits for incoming connection */
 if (BIO_do_accept(acpt) <= 0) {
    fprintf(stderr, "Error accepting connection\en");
    ERR_print_errors_fp(stderr);
    \fBexit\fP\|(1);
 }
.PP
.Vb 3
\& /* 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\en");
\&     ERR_print_errors_fp(stderr);
\&     exit(1);
\& }
\&
\& BIO_puts(sbio, "HTTP/1.0 200 OK\er\enContent\-type: text/plain\er\en\er\en");
\& BIO_puts(sbio, "\er\enConnection Established\er\enRequest headers:\er\en");
\& BIO_puts(sbio, "\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\er\en");
\&
\& 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] == \*(Aq\er\*(Aq || tmpbuf[0] == \*(Aq\en\*(Aq)
\&         break;
\& }
\&
\& BIO_puts(sbio, "\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\er\en");
\& BIO_puts(sbio, "\er\en");
\& BIO_flush(sbio);
\& BIO_free_all(sbio);
.Ve
.SH التاريخ
.IX Header التاريخ
في OpenSSL قبل 1.0.0، عُولجت استدعاء \fBBIO_pop()\fP بشكل غير صحيح، زيد عدد
مراجع I/O BIO بشكل غير صحيح (بدلاً من إنقاصه) وفُصل عن SSL BIO حتى لو لم
يُفصل SSL BIO صراحة (مثل فصل أعلى السلسلة). يجب تعديل التطبيقات التي تضمنت
حلولاً بديلة لهذا الخلل (مثل تحرير BIOs أكثر من مرة) لمعالجة هذا الإصلاح أو
قد تحرر BIO محرر بالفعل.
.SH "حقوق النسخ"
.IX Header "حقوق النسخ"
حقوق النشر 2000\-2023 لمؤلفي مشروع OpenSSL. جميع الحقوق محفوظة.
.PP
مرخص بموجب رخصة Apache 2.0 (المشار إليها فيما يلي بـ ”الرخصة“).  لا يجوز لك
استخدام هذا الملف إلا وفقًا لشروط الرخصة.  يمكنك الحصول على نسخة منها في
الملف LICENSE الموجود في حزمة التوزيع المصدرية أو على الرابط
<https://www.openssl.org/source/license.html>.
.PP
.SH ترجمة
تُرجمت هذه الصفحة من الدليل بواسطة
زايد السعيدي <zayed.alsaidi@gmail.com>
.
.PP
هذه الترجمة هي وثيقة مجانية؛ راجع
.UR https://www.gnu.org/licenses/gpl-3.0.html 
رخصة جنو العامة الإصدار 3
.UE
أو ما بعده للاطلاع على شروط حقوق النشر.
لا توجد أي ضمانات.
.PP
إذا وجدت أي أخطاء في ترجمة صفحة الدليل هذه،
يرجى إرسال بريد إلكتروني إلى قائمة بريد المترجمين:
.MT kde-l10n-ar@kde.org
.ME .