1BIO_F_SSL(3) OpenSSL BIO_F_SSL(3)
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 BIO b to ssl using the
55 close flag c.
56 BIO_get_ssl() retrieves the SSL pointer of 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 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 BIO_set_ssl_renegotiate_timeout() sets the renegotiate timeout to
68 seconds. When the renegotiate timeout elapses the session is
69 automatically renegotiated.
70 BIO_get_num_renegotiates() returns the total number of session
72 renegotiations due to I/O or timeout.
73 BIO_new_ssl() allocates an SSL BIO using SSL_CTX ctx and using client
75 mode if client is non zero.
76 BIO_new_ssl_connect() creates a new BIO chain consisting of an SSL BIO
78 (using ctx) followed by a connect BIO.
79 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 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 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 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
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 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 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 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 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
124 This SSL/TLS client example, attempts to retrieve a page from an
125 SSL/TLS web server. The I/O routines are identical to those of the
126 unencrypted example in BIO_s_connect(3).
127 BIO *sbio, *out;
129 int len;
130 char tmpbuf[1024];
131 SSL_CTX *ctx;
132 SSL *ssl;
133 /* XXX Seed the PRNG if needed. */
135 ctx = SSL_CTX_new(TLS_client_method());
137 /* XXX Set verify paths and mode here. */
139 sbio = BIO_new_ssl_connect(ctx);
141 BIO_get_ssl(sbio, &ssl);
142 if (ssl == NULL) {
143 fprintf(stderr, "Can't locate SSL pointer\n");
144 ERR_print_errors_fp(stderr);
145 exit(1);
146 }
147 /* Don't want any retries */
149 SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY);
150 /* XXX We might want to do other things with ssl here */
152 /* An empty host part means the loopback address */
154 BIO_set_conn_hostname(sbio, ":https");
155 out = BIO_new_fp(stdout, BIO_NOCLOSE);
157 if (BIO_do_connect(sbio) <= 0) {
158 fprintf(stderr, "Error connecting to server\n");
159 ERR_print_errors_fp(stderr);
160 exit(1);
161 }
162 if (BIO_do_handshake(sbio) <= 0) {
163 fprintf(stderr, "Error establishing SSL connection\n");
164 ERR_print_errors_fp(stderr);
165 exit(1);
166 }
167 /* XXX Could examine ssl here to get connection info */
169 BIO_puts(sbio, "GET / HTTP/1.0\n\n");
171 for (;;) {
172 len = BIO_read(sbio, tmpbuf, 1024);
173 if (len <= 0)
174 break;
175 BIO_write(out, tmpbuf, len);
176 }
177 BIO_free_all(sbio);
178 BIO_free(out);
179 Here is a simple server example. It makes use of a buffering BIO to
181 allow lines to be read from the SSL BIO using BIO_gets. It creates a
182 pseudo web page containing the actual request from a client and also
183 echoes the request to standard output.
184 BIO *sbio, *bbio, *acpt, *out;
186 int len;
187 char tmpbuf[1024];
188 SSL_CTX *ctx;
189 SSL *ssl;
190 /* XXX Seed the PRNG if needed. */
192 ctx = SSL_CTX_new(TLS_server_method());
194 if (!SSL_CTX_use_certificate_file(ctx, "server.pem", SSL_FILETYPE_PEM)
195 || !SSL_CTX_use_PrivateKey_file(ctx, "server.pem", SSL_FILETYPE_PEM)
196 || !SSL_CTX_check_private_key(ctx)) {
197 fprintf(stderr, "Error setting up SSL_CTX\n");
198 ERR_print_errors_fp(stderr);
199 exit(1);
200 }
201 /* XXX Other things like set verify locations, EDH temp callbacks. */
203 /* New SSL BIO setup as server */
205 sbio = BIO_new_ssl(ctx, 0);
206 BIO_get_ssl(sbio, &ssl);
207 if (ssl == NULL) {
208 fprintf(stderr, "Can't locate SSL pointer\n");
209 ERR_print_errors_fp(stderr);
210 exit(1);
211 }
212 SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY);
214 bbio = BIO_new(BIO_f_buffer());
215 sbio = BIO_push(bbio, sbio);
216 acpt = BIO_new_accept("4433");
217 /*
219 * By doing this when a new connection is established
220 * we automatically have sbio inserted into it. The
221 * BIO chain is now 'swallowed' by the accept BIO and
222 * will be freed when the accept BIO is freed.
223 */
224 BIO_set_accept_bios(acpt, sbio);
225 out = BIO_new_fp(stdout, BIO_NOCLOSE);
226 /* Setup accept BIO */
228 if (BIO_do_accept(acpt) <= 0) {
229 fprintf(stderr, "Error setting up accept BIO\n");
230 ERR_print_errors_fp(stderr);
231 exit(1);
232 }
233 /* We only want one connection so remove and free accept BIO */
235 sbio = BIO_pop(acpt);
236 BIO_free_all(acpt);
237 if (BIO_do_handshake(sbio) <= 0) {
239 fprintf(stderr, "Error in SSL handshake\n");
240 ERR_print_errors_fp(stderr);
241 exit(1);
242 }
243 BIO_puts(sbio, "HTTP/1.0 200 OK\r\nContent-type: text/plain\r\n\r\n");
245 BIO_puts(sbio, "\r\nConnection Established\r\nRequest headers:\r\n");
246 BIO_puts(sbio, "--------------------------------------------------\r\n");
247 for (;;) {
249 len = BIO_gets(sbio, tmpbuf, 1024);
250 if (len <= 0)
251 break;
252 BIO_write(sbio, tmpbuf, len);
253 BIO_write(out, tmpbuf, len);
254 /* Look for blank line signifying end of headers*/
255 if (tmpbuf[0] == '\r' || tmpbuf[0] == '\n')
256 break;
257 }
258 BIO_puts(sbio, "--------------------------------------------------\r\n");
260 BIO_puts(sbio, "\r\n");
261 BIO_flush(sbio);
262 BIO_free_all(sbio);
263
265 BIO_f_ssl() returns the SSL BIO_METHOD structure.
266 BIO_set_ssl(), BIO_get_ssl(), BIO_set_ssl_mode(),
268 BIO_set_ssl_renegotiate_bytes(), BIO_set_ssl_renegotiate_timeout() and
269 BIO_get_num_renegotiates() return 1 on success or a value which is less
270 than or equal to 0 if an error occurred.
271 BIO_new_ssl(), BIO_new_ssl_connect() and BIO_new_buffer_ssl_connect()
273 return a valid BIO structure on success or NULL if an error occurred.
274 BIO_ssl_copy_session_id() returns 1 on success or 0 on error.
276 BIO_do_handshake() returns 1 if the connection was established
278 successfully. A zero or negative value is returned if the connection
279 could not be established.
280
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-2018 The OpenSSL Project Authors. All Rights Reserved.
292 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>.
2971.1.1 2018-09-11 BIO_F_SSL(3)