1BIO_F_SSL(3)                        OpenSSL                       BIO_F_SSL(3)
2
3
4

NAME

6       BIO_do_handshake, BIO_f_ssl, BIO_set_ssl, BIO_get_ssl,
7       BIO_set_ssl_mode, BIO_set_ssl_renegotiate_bytes,
8       BIO_get_num_renegotiates, BIO_set_ssl_renegotiate_timeout, BIO_new_ssl,
9       BIO_new_ssl_connect, BIO_new_buffer_ssl_connect,
10       BIO_ssl_copy_session_id, BIO_ssl_shutdown - SSL BIO
11

SYNOPSIS

13        #include <openssl/bio.h>
14        #include <openssl/ssl.h>
15
16        const BIO_METHOD *BIO_f_ssl(void);
17
18        long BIO_set_ssl(BIO *b, SSL *ssl, long c);
19        long BIO_get_ssl(BIO *b, SSL **sslp);
20        long BIO_set_ssl_mode(BIO *b, long client);
21        long BIO_set_ssl_renegotiate_bytes(BIO *b, long num);
22        long BIO_set_ssl_renegotiate_timeout(BIO *b, long seconds);
23        long BIO_get_num_renegotiates(BIO *b);
24
25        BIO *BIO_new_ssl(SSL_CTX *ctx, int client);
26        BIO *BIO_new_ssl_connect(SSL_CTX *ctx);
27        BIO *BIO_new_buffer_ssl_connect(SSL_CTX *ctx);
28        int BIO_ssl_copy_session_id(BIO *to, BIO *from);
29        void BIO_ssl_shutdown(BIO *bio);
30
31        long BIO_do_handshake(BIO *b);
32

DESCRIPTION

34       BIO_f_ssl() returns the SSL BIO method. This is a filter BIO which is a
35       wrapper round the OpenSSL SSL routines adding a BIO "flavour" to SSL
36       I/O.
37
38       I/O performed on an SSL BIO communicates using the SSL protocol with
39       the SSLs read and write BIOs. If an SSL connection is not established
40       then an attempt is made to establish one on the first I/O call.
41
42       If a BIO is appended to an SSL BIO using BIO_push() it is automatically
43       used as the SSL BIOs read and write BIOs.
44
45       Calling BIO_reset() on an SSL BIO closes down any current SSL
46       connection by calling SSL_shutdown(). BIO_reset() is then sent to the
47       next BIO in the chain: this will typically disconnect the underlying
48       transport.  The SSL BIO is then reset to the initial accept or connect
49       state.
50
51       If the close flag is set when an SSL BIO is freed then the internal SSL
52       structure is also freed using SSL_free().
53
54       BIO_set_ssl() sets the internal SSL pointer of BIO b to ssl using the
55       close flag c.
56
57       BIO_get_ssl() retrieves the SSL pointer of BIO b, it can then be
58       manipulated using the standard SSL library functions.
59
60       BIO_set_ssl_mode() sets the SSL BIO mode to client. If client is 1
61       client mode is set. If client is 0 server mode is set.
62
63       BIO_set_ssl_renegotiate_bytes() sets the renegotiate byte count to num.
64       When set after every num bytes of I/O (read and write) the SSL session
65       is automatically renegotiated. num must be at least 512 bytes.
66
67       BIO_set_ssl_renegotiate_timeout() sets the renegotiate timeout to
68       seconds. When the renegotiate timeout elapses the session is
69       automatically renegotiated.
70
71       BIO_get_num_renegotiates() returns the total number of session
72       renegotiations due to I/O or timeout.
73
74       BIO_new_ssl() allocates an SSL BIO using SSL_CTX ctx and using client
75       mode if client is non zero.
76
77       BIO_new_ssl_connect() creates a new BIO chain consisting of an SSL BIO
78       (using ctx) followed by a connect BIO.
79
80       BIO_new_buffer_ssl_connect() creates a new BIO chain consisting of a
81       buffering BIO, an SSL BIO (using ctx) and a connect BIO.
82
83       BIO_ssl_copy_session_id() copies an SSL session id between BIO chains
84       from and to. It does this by locating the SSL BIOs in each chain and
85       calling SSL_copy_session_id() on the internal SSL pointer.
86
87       BIO_ssl_shutdown() closes down an SSL connection on BIO chain bio. It
88       does this by locating the SSL BIO in the chain and calling
89       SSL_shutdown() on its internal SSL pointer.
90
91       BIO_do_handshake() attempts to complete an SSL handshake on the
92       supplied BIO and establish the SSL connection. It returns 1 if the
93       connection was established successfully. A zero or negative value is
94       returned if the connection could not be established, the call
95       BIO_should_retry() should be used for non blocking connect BIOs to
96       determine if the call should be retried. If an SSL connection has
97       already been established this call has no effect.
98

NOTES

100       SSL BIOs are exceptional in that if the underlying transport is non
101       blocking they can still request a retry in exceptional circumstances.
102       Specifically this will happen if a session renegotiation takes place
103       during a BIO_read_ex() operation, one case where this happens is when
104       step up occurs.
105
106       The SSL flag SSL_AUTO_RETRY can be set to disable this behaviour. That
107       is when this flag is set an SSL BIO using a blocking transport will
108       never request a retry.
109
110       Since unknown BIO_ctrl() operations are sent through filter BIOs the
111       servers name and port can be set using BIO_set_host() on the BIO
112       returned by BIO_new_ssl_connect() without having to locate the connect
113       BIO first.
114
115       Applications do not have to call BIO_do_handshake() but may wish to do
116       so to separate the handshake process from other I/O processing.
117
118       BIO_set_ssl(), BIO_get_ssl(), BIO_set_ssl_mode(),
119       BIO_set_ssl_renegotiate_bytes(), BIO_set_ssl_renegotiate_timeout(),
120       BIO_get_num_renegotiates(), and BIO_do_handshake() are implemented as
121       macros.
122

RETURN VALUES

124       BIO_f_ssl() returns the SSL BIO_METHOD structure.
125
126       BIO_set_ssl(), BIO_get_ssl(), BIO_set_ssl_mode(),
127       BIO_set_ssl_renegotiate_bytes(), BIO_set_ssl_renegotiate_timeout() and
128       BIO_get_num_renegotiates() return 1 on success or a value which is less
129       than or equal to 0 if an error occurred.
130
131       BIO_new_ssl(), BIO_new_ssl_connect() and BIO_new_buffer_ssl_connect()
132       return a valid BIO structure on success or NULL if an error occurred.
133
134       BIO_ssl_copy_session_id() returns 1 on success or 0 on error.
135
136       BIO_do_handshake() returns 1 if the connection was established
137       successfully.  A zero or negative value is returned if the connection
138       could not be established.
139

EXAMPLES

141       This SSL/TLS client example attempts to retrieve a page from an SSL/TLS
142       web server. The I/O routines are identical to those of the unencrypted
143       example in BIO_s_connect(3).
144
145        BIO *sbio, *out;
146        int len;
147        char tmpbuf[1024];
148        SSL_CTX *ctx;
149        SSL *ssl;
150
151        /* XXX Seed the PRNG if needed. */
152
153        ctx = SSL_CTX_new(TLS_client_method());
154
155        /* XXX Set verify paths and mode here. */
156
157        sbio = BIO_new_ssl_connect(ctx);
158        BIO_get_ssl(sbio, &ssl);
159        if (ssl == NULL) {
160            fprintf(stderr, "Can't locate SSL pointer\n");
161            ERR_print_errors_fp(stderr);
162            exit(1);
163        }
164
165        /* Don't want any retries */
166        SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY);
167
168        /* XXX We might want to do other things with ssl here */
169
170        /* An empty host part means the loopback address */
171        BIO_set_conn_hostname(sbio, ":https");
172
173        out = BIO_new_fp(stdout, BIO_NOCLOSE);
174        if (BIO_do_connect(sbio) <= 0) {
175            fprintf(stderr, "Error connecting to server\n");
176            ERR_print_errors_fp(stderr);
177            exit(1);
178        }
179        if (BIO_do_handshake(sbio) <= 0) {
180            fprintf(stderr, "Error establishing SSL connection\n");
181            ERR_print_errors_fp(stderr);
182            exit(1);
183        }
184
185        /* XXX Could examine ssl here to get connection info */
186
187        BIO_puts(sbio, "GET / HTTP/1.0\n\n");
188        for (;;) {
189            len = BIO_read(sbio, tmpbuf, 1024);
190            if (len <= 0)
191                break;
192            BIO_write(out, tmpbuf, len);
193        }
194        BIO_free_all(sbio);
195        BIO_free(out);
196
197       Here is a simple server example. It makes use of a buffering BIO to
198       allow lines to be read from the SSL BIO using BIO_gets.  It creates a
199       pseudo web page containing the actual request from a client and also
200       echoes the request to standard output.
201
202        BIO *sbio, *bbio, *acpt, *out;
203        int len;
204        char tmpbuf[1024];
205        SSL_CTX *ctx;
206        SSL *ssl;
207
208        /* XXX Seed the PRNG if needed. */
209
210        ctx = SSL_CTX_new(TLS_server_method());
211        if (!SSL_CTX_use_certificate_file(ctx, "server.pem", SSL_FILETYPE_PEM)
212                || !SSL_CTX_use_PrivateKey_file(ctx, "server.pem", SSL_FILETYPE_PEM)
213                || !SSL_CTX_check_private_key(ctx)) {
214            fprintf(stderr, "Error setting up SSL_CTX\n");
215            ERR_print_errors_fp(stderr);
216            exit(1);
217        }
218
219        /* XXX Other things like set verify locations, EDH temp callbacks. */
220
221        /* New SSL BIO setup as server */
222        sbio = BIO_new_ssl(ctx, 0);
223        BIO_get_ssl(sbio, &ssl);
224        if (ssl == NULL) {
225            fprintf(stderr, "Can't locate SSL pointer\n");
226            ERR_print_errors_fp(stderr);
227            exit(1);
228        }
229
230        SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY);
231        bbio = BIO_new(BIO_f_buffer());
232        sbio = BIO_push(bbio, sbio);
233        acpt = BIO_new_accept("4433");
234
235        /*
236         * By doing this when a new connection is established
237         * we automatically have sbio inserted into it. The
238         * BIO chain is now 'swallowed' by the accept BIO and
239         * will be freed when the accept BIO is freed.
240         */
241        BIO_set_accept_bios(acpt, sbio);
242        out = BIO_new_fp(stdout, BIO_NOCLOSE);
243
244        /* Setup accept BIO */
245        if (BIO_do_accept(acpt) <= 0) {
246            fprintf(stderr, "Error setting up accept BIO\n");
247            ERR_print_errors_fp(stderr);
248            exit(1);
249        }
250
251        /* We only want one connection so remove and free accept BIO */
252        sbio = BIO_pop(acpt);
253        BIO_free_all(acpt);
254
255        if (BIO_do_handshake(sbio) <= 0) {
256            fprintf(stderr, "Error in SSL handshake\n");
257            ERR_print_errors_fp(stderr);
258            exit(1);
259        }
260
261        BIO_puts(sbio, "HTTP/1.0 200 OK\r\nContent-type: text/plain\r\n\r\n");
262        BIO_puts(sbio, "\r\nConnection Established\r\nRequest headers:\r\n");
263        BIO_puts(sbio, "--------------------------------------------------\r\n");
264
265        for (;;) {
266            len = BIO_gets(sbio, tmpbuf, 1024);
267            if (len <= 0)
268                break;
269            BIO_write(sbio, tmpbuf, len);
270            BIO_write(out, tmpbuf, len);
271            /* Look for blank line signifying end of headers*/
272            if (tmpbuf[0] == '\r' || tmpbuf[0] == '\n')
273                break;
274        }
275
276        BIO_puts(sbio, "--------------------------------------------------\r\n");
277        BIO_puts(sbio, "\r\n");
278        BIO_flush(sbio);
279        BIO_free_all(sbio);
280

HISTORY

282       In OpenSSL before 1.0.0 the BIO_pop() call was handled incorrectly, the
283       I/O BIO reference count was incorrectly incremented (instead of
284       decremented) and dissociated with the SSL BIO even if the SSL BIO was
285       not explicitly being popped (e.g. a pop higher up the chain).
286       Applications which included workarounds for this bug (e.g. freeing BIOs
287       more than once) should be modified to handle this fix or they may free
288       up an already freed BIO.
289
291       Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
292
293       Licensed under the OpenSSL license (the "License").  You may not use
294       this file except in compliance with the License.  You can obtain a copy
295       in the file LICENSE in the source distribution or at
296       <https://www.openssl.org/source/license.html>.
297
298
299
3001.1.1g                            2020-04-23                      BIO_F_SSL(3)
Impressum