1BIO_F_SSL(3ossl) OpenSSL BIO_F_SSL(3ossl)
2
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
13 #include <openssl/bio.h>
14 #include <openssl/ssl.h>
15 const BIO_METHOD *BIO_f_ssl(void);
17 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 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 long BIO_do_handshake(BIO *b);
32
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 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 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 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 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 BIO_set_ssl() sets the internal SSL pointer of SSL BIO b to ssl using
55 the close flag c.
56 BIO_get_ssl() retrieves the SSL pointer of SSL BIO b, it can then be
58 manipulated using the standard SSL library functions.
59 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 BIO_set_ssl_renegotiate_bytes() sets the renegotiate byte count of SSL
64 BIO b to num. When set after every num bytes of I/O (read and write)
65 the SSL session is automatically renegotiated. num must be at least 512
66 bytes.
67 BIO_set_ssl_renegotiate_timeout() sets the renegotiate timeout of SSL
69 BIO b to seconds. When the renegotiate timeout elapses the session is
70 automatically renegotiated.
71 BIO_get_num_renegotiates() returns the total number of session
73 renegotiations due to I/O or timeout of SSL BIO b.
74 BIO_new_ssl() allocates an SSL BIO using SSL_CTX ctx and using client
76 mode if client is non zero.
77 BIO_new_ssl_connect() creates a new BIO chain consisting of an SSL BIO
79 (using ctx) followed by a connect BIO.
80 BIO_new_buffer_ssl_connect() creates a new BIO chain consisting of a
82 buffering BIO, an SSL BIO (using ctx), and a connect BIO.
83 BIO_ssl_copy_session_id() copies an SSL session id between BIO chains
85 from and to. It does this by locating the SSL BIOs in each chain and
86 calling SSL_copy_session_id() on the internal SSL pointer.
87 BIO_ssl_shutdown() closes down an SSL connection on BIO chain bio. It
89 does this by locating the SSL BIO in the chain and calling
90 SSL_shutdown() on its internal SSL pointer.
91 BIO_do_handshake() attempts to complete an SSL handshake on the
93 supplied BIO and establish the SSL connection. For non-SSL BIOs the
94 connection is done typically at TCP level. If domain name resolution
95 yields multiple IP addresses all of them are tried after connect()
96 failures. The function returns 1 if the connection was established
97 successfully. A zero or negative value is returned if the connection
98 could not be established. The call BIO_should_retry() should be used
99 for nonblocking connect BIOs to determine if the call should be
100 retried. If a connection has already been established this call has no
101 effect.
102
104 SSL BIOs are exceptional in that if the underlying transport is non
105 blocking they can still request a retry in exceptional circumstances.
106 Specifically this will happen if a session renegotiation takes place
107 during a BIO_read_ex() operation, one case where this happens is when
108 step up occurs.
109 The SSL flag SSL_AUTO_RETRY can be set to disable this behaviour. That
111 is when this flag is set an SSL BIO using a blocking transport will
112 never request a retry.
113 Since unknown BIO_ctrl() operations are sent through filter BIOs the
115 servers name and port can be set using BIO_set_host() on the BIO
116 returned by BIO_new_ssl_connect() without having to locate the connect
117 BIO first.
118 Applications do not have to call BIO_do_handshake() but may wish to do
120 so to separate the handshake process from other I/O processing.
121 BIO_set_ssl(), BIO_get_ssl(), BIO_set_ssl_mode(),
123 BIO_set_ssl_renegotiate_bytes(), BIO_set_ssl_renegotiate_timeout(),
124 BIO_get_num_renegotiates(), and BIO_do_handshake() are implemented as
125 macros.
126
128 BIO_f_ssl() returns the SSL BIO_METHOD structure.
129 BIO_set_ssl(), BIO_get_ssl(), BIO_set_ssl_mode(),
131 BIO_set_ssl_renegotiate_bytes(), BIO_set_ssl_renegotiate_timeout() and
132 BIO_get_num_renegotiates() return 1 on success or a value which is less
133 than or equal to 0 if an error occurred.
134 BIO_new_ssl(), BIO_new_ssl_connect() and BIO_new_buffer_ssl_connect()
136 return a valid BIO structure on success or NULL if an error occurred.
137 BIO_ssl_copy_session_id() returns 1 on success or 0 on error.
139 BIO_do_handshake() returns 1 if the connection was established
141 successfully. A zero or negative value is returned if the connection
142 could not be established.
143
145 This SSL/TLS client example attempts to retrieve a page from an SSL/TLS
146 web server. The I/O routines are identical to those of the unencrypted
147 example in BIO_s_connect(3).
148 BIO *sbio, *out;
150 int len;
151 char tmpbuf[1024];
152 SSL_CTX *ctx;
153 SSL *ssl;
154 /* XXX Seed the PRNG if needed. */
156 ctx = SSL_CTX_new(TLS_client_method());
158 /* XXX Set verify paths and mode here. */
160 sbio = BIO_new_ssl_connect(ctx);
162 BIO_get_ssl(sbio, &ssl);
163 if (ssl == NULL) {
164 fprintf(stderr, "Can't locate SSL pointer\n");
165 ERR_print_errors_fp(stderr);
166 exit(1);
167 }
168 /* XXX We might want to do other things with ssl here */
170 /* An empty host part means the loopback address */
172 BIO_set_conn_hostname(sbio, ":https");
173 out = BIO_new_fp(stdout, BIO_NOCLOSE);
175 if (BIO_do_connect(sbio) <= 0) {
176 fprintf(stderr, "Error connecting to server\n");
177 ERR_print_errors_fp(stderr);
178 exit(1);
179 }
180 /* XXX Could examine ssl here to get connection info */
182 BIO_puts(sbio, "GET / HTTP/1.0\n\n");
184 for (;;) {
185 len = BIO_read(sbio, tmpbuf, 1024);
186 if (len <= 0)
187 break;
188 BIO_write(out, tmpbuf, len);
189 }
190 BIO_free_all(sbio);
191 BIO_free(out);
192 Here is a simple server example. It makes use of a buffering BIO to
194 allow lines to be read from the SSL BIO using BIO_gets. It creates a
195 pseudo web page containing the actual request from a client and also
196 echoes the request to standard output.
197 BIO *sbio, *bbio, *acpt, *out;
199 int len;
200 char tmpbuf[1024];
201 SSL_CTX *ctx;
202 SSL *ssl;
203 /* XXX Seed the PRNG if needed. */
205 ctx = SSL_CTX_new(TLS_server_method());
207 if (!SSL_CTX_use_certificate_file(ctx, "server.pem", SSL_FILETYPE_PEM)
208 || !SSL_CTX_use_PrivateKey_file(ctx, "server.pem", SSL_FILETYPE_PEM)
209 || !SSL_CTX_check_private_key(ctx)) {
210 fprintf(stderr, "Error setting up SSL_CTX\n");
211 ERR_print_errors_fp(stderr);
212 exit(1);
213 }
214 /* XXX Other things like set verify locations, EDH temp callbacks. */
216 /* New SSL BIO setup as server */
218 sbio = BIO_new_ssl(ctx, 0);
219 BIO_get_ssl(sbio, &ssl);
220 if (ssl == NULL) {
221 fprintf(stderr, "Can't locate SSL pointer\n");
222 ERR_print_errors_fp(stderr);
223 exit(1);
224 }
225 bbio = BIO_new(BIO_f_buffer());
227 sbio = BIO_push(bbio, sbio);
228 acpt = BIO_new_accept("4433");
229 /*
231 * By doing this when a new connection is established
232 * we automatically have sbio inserted into it. The
233 * BIO chain is now 'swallowed' by the accept BIO and
234 * will be freed when the accept BIO is freed.
235 */
236 BIO_set_accept_bios(acpt, sbio);
237 out = BIO_new_fp(stdout, BIO_NOCLOSE);
238 /* First call to BIO_do_accept() sets up accept BIO */
240 if (BIO_do_accept(acpt) <= 0) {
241 fprintf(stderr, "Error setting up accept BIO\n");
242 ERR_print_errors_fp(stderr);
243 exit(1);
244 }
245 /* Second call to BIO_do_accept() waits for incoming connection */
247 if (BIO_do_accept(acpt) <= 0) {
248 fprintf(stderr, "Error accepting connection\n");
249 ERR_print_errors_fp(stderr);
250 exit(1);
251 }
252 /* We only want one connection so remove and free accept BIO */
254 sbio = BIO_pop(acpt);
255 BIO_free_all(acpt);
256 if (BIO_do_handshake(sbio) <= 0) {
258 fprintf(stderr, "Error in SSL handshake\n");
259 ERR_print_errors_fp(stderr);
260 exit(1);
261 }
262 BIO_puts(sbio, "HTTP/1.0 200 OK\r\nContent-type: text/plain\r\n\r\n");
264 BIO_puts(sbio, "\r\nConnection Established\r\nRequest headers:\r\n");
265 BIO_puts(sbio, "--------------------------------------------------\r\n");
266 for (;;) {
268 len = BIO_gets(sbio, tmpbuf, 1024);
269 if (len <= 0)
270 break;
271 BIO_write(sbio, tmpbuf, len);
272 BIO_write(out, tmpbuf, len);
273 /* Look for blank line signifying end of headers*/
274 if (tmpbuf[0] == '\r' || tmpbuf[0] == '\n')
275 break;
276 }
277 BIO_puts(sbio, "--------------------------------------------------\r\n");
279 BIO_puts(sbio, "\r\n");
280 BIO_flush(sbio);
281 BIO_free_all(sbio);
282
284 In OpenSSL before 1.0.0 the BIO_pop() call was handled incorrectly, the
285 I/O BIO reference count was incorrectly incremented (instead of
286 decremented) and dissociated with the SSL BIO even if the SSL BIO was
287 not explicitly being popped (e.g. a pop higher up the chain).
288 Applications which included workarounds for this bug (e.g. freeing BIOs
289 more than once) should be modified to handle this fix or they may free
290 up an already freed BIO.
291
293 Copyright 2000-2022 The OpenSSL Project Authors. All Rights Reserved.
294 Licensed under the Apache License 2.0 (the "License"). You may not use
296 this file except in compliance with the License. You can obtain a copy
297 in the file LICENSE in the source distribution or at
298 <https://www.openssl.org/source/license.html>.
2993.1.1 2023-08-31 BIO_F_SSL(3ossl)