]>
Commit | Line | Data |
---|---|---|
32751b8a DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
c952780c RS |
5 | BIO_do_handshake, |
6 | BIO_f_ssl, BIO_set_ssl, BIO_get_ssl, BIO_set_ssl_mode, | |
7 | BIO_set_ssl_renegotiate_bytes, | |
32751b8a DSH |
8 | BIO_get_num_renegotiates, BIO_set_ssl_renegotiate_timeout, BIO_new_ssl, |
9 | BIO_new_ssl_connect, BIO_new_buffer_ssl_connect, BIO_ssl_copy_session_id, | |
10 | BIO_ssl_shutdown - SSL BIO | |
11 | ||
12 | =head1 SYNOPSIS | |
13 | ||
bb82531f | 14 | =for openssl multiple includes |
b97fdb57 | 15 | |
32751b8a DSH |
16 | #include <openssl/bio.h> |
17 | #include <openssl/ssl.h> | |
18 | ||
04f6b0fd | 19 | const BIO_METHOD *BIO_f_ssl(void); |
32751b8a | 20 | |
aebb9aac | 21 | long BIO_set_ssl(BIO *b, SSL *ssl, long c); |
91da5e77 RS |
22 | long BIO_get_ssl(BIO *b, SSL **sslp); |
23 | long BIO_set_ssl_mode(BIO *b, long client); | |
24 | long BIO_set_ssl_renegotiate_bytes(BIO *b, long num); | |
25 | long BIO_set_ssl_renegotiate_timeout(BIO *b, long seconds); | |
26 | long BIO_get_num_renegotiates(BIO *b); | |
27 | ||
28 | BIO *BIO_new_ssl(SSL_CTX *ctx, int client); | |
32751b8a DSH |
29 | BIO *BIO_new_ssl_connect(SSL_CTX *ctx); |
30 | BIO *BIO_new_buffer_ssl_connect(SSL_CTX *ctx); | |
91da5e77 | 31 | int BIO_ssl_copy_session_id(BIO *to, BIO *from); |
32751b8a DSH |
32 | void BIO_ssl_shutdown(BIO *bio); |
33 | ||
91da5e77 | 34 | long BIO_do_handshake(BIO *b); |
2c281ebb | 35 | |
32751b8a DSH |
36 | =head1 DESCRIPTION |
37 | ||
38 | BIO_f_ssl() returns the SSL BIO method. This is a filter BIO which | |
acb5b343 | 39 | is a wrapper round the OpenSSL SSL routines adding a BIO "flavour" to |
1bc74519 | 40 | SSL I/O. |
32751b8a DSH |
41 | |
42 | I/O performed on an SSL BIO communicates using the SSL protocol with | |
2c281ebb DSH |
43 | the SSLs read and write BIOs. If an SSL connection is not established |
44 | then an attempt is made to establish one on the first I/O call. | |
32751b8a DSH |
45 | |
46 | If a BIO is appended to an SSL BIO using BIO_push() it is automatically | |
47 | used as the SSL BIOs read and write BIOs. | |
48 | ||
49 | Calling BIO_reset() on an SSL BIO closes down any current SSL connection | |
50 | by calling SSL_shutdown(). BIO_reset() is then sent to the next BIO in | |
51 | the chain: this will typically disconnect the underlying transport. | |
52 | The SSL BIO is then reset to the initial accept or connect state. | |
53 | ||
54 | If the close flag is set when an SSL BIO is freed then the internal | |
55 | SSL structure is also freed using SSL_free(). | |
56 | ||
34901b0c | 57 | BIO_set_ssl() sets the internal SSL pointer of SSL BIO B<b> to B<ssl> using |
32751b8a DSH |
58 | the close flag B<c>. |
59 | ||
34901b0c | 60 | BIO_get_ssl() retrieves the SSL pointer of SSL BIO B<b>, it can then be |
32751b8a DSH |
61 | manipulated using the standard SSL library functions. |
62 | ||
63 | BIO_set_ssl_mode() sets the SSL BIO mode to B<client>. If B<client> | |
64 | is 1 client mode is set. If B<client> is 0 server mode is set. | |
65 | ||
34901b0c | 66 | BIO_set_ssl_renegotiate_bytes() sets the renegotiate byte count of SSL BIO B<b> |
1bc74519 | 67 | to B<num>. When set after every B<num> bytes of I/O (read and write) |
32751b8a DSH |
68 | the SSL session is automatically renegotiated. B<num> must be at |
69 | least 512 bytes. | |
70 | ||
34901b0c DDO |
71 | BIO_set_ssl_renegotiate_timeout() sets the renegotiate timeout of SSL BIO B<b> |
72 | to B<seconds>. | |
73 | When the renegotiate timeout elapses the session is automatically renegotiated. | |
32751b8a DSH |
74 | |
75 | BIO_get_num_renegotiates() returns the total number of session | |
34901b0c | 76 | renegotiations due to I/O or timeout of SSL BIO B<b>. |
32751b8a DSH |
77 | |
78 | BIO_new_ssl() allocates an SSL BIO using SSL_CTX B<ctx> and using | |
79 | client mode if B<client> is non zero. | |
80 | ||
81 | BIO_new_ssl_connect() creates a new BIO chain consisting of an | |
82 | SSL BIO (using B<ctx>) followed by a connect BIO. | |
83 | ||
84 | BIO_new_buffer_ssl_connect() creates a new BIO chain consisting | |
34901b0c | 85 | of a buffering BIO, an SSL BIO (using B<ctx>), and a connect BIO. |
32751b8a | 86 | |
1bc74519 | 87 | BIO_ssl_copy_session_id() copies an SSL session id between |
32751b8a DSH |
88 | BIO chains B<from> and B<to>. It does this by locating the |
89 | SSL BIOs in each chain and calling SSL_copy_session_id() on | |
90 | the internal SSL pointer. | |
91 | ||
92 | BIO_ssl_shutdown() closes down an SSL connection on BIO | |
93 | chain B<bio>. It does this by locating the SSL BIO in the | |
94 | chain and calling SSL_shutdown() on its internal SSL | |
95 | pointer. | |
96 | ||
2c281ebb | 97 | BIO_do_handshake() attempts to complete an SSL handshake on the |
34901b0c | 98 | supplied BIO and establish the SSL connection. |
59131529 DDO |
99 | For non-SSL BIOs the connection is done typically at TCP level. |
100 | If domain name resolution yields multiple IP addresses all of them are tried | |
101 | after connect() failures. | |
102 | The function returns 1 if the connection was established successfully. | |
103 | A zero or negative value is returned if the connection could not be established. | |
490c8711 | 104 | The call BIO_should_retry() should be used for nonblocking connect BIOs |
59131529 DDO |
105 | to determine if the call should be retried. |
106 | If a connection has already been established this call has no effect. | |
2c281ebb | 107 | |
32751b8a DSH |
108 | =head1 NOTES |
109 | ||
110 | SSL BIOs are exceptional in that if the underlying transport | |
111 | is non blocking they can still request a retry in exceptional | |
112 | circumstances. Specifically this will happen if a session | |
b055fceb | 113 | renegotiation takes place during a BIO_read_ex() operation, one |
63eab8a6 | 114 | case where this happens is when step up occurs. |
32751b8a | 115 | |
a528d4f0 | 116 | The SSL flag SSL_AUTO_RETRY can be |
acb5b343 | 117 | set to disable this behaviour. That is when this flag is set |
32751b8a DSH |
118 | an SSL BIO using a blocking transport will never request a |
119 | retry. | |
120 | ||
121 | Since unknown BIO_ctrl() operations are sent through filter | |
122 | BIOs the servers name and port can be set using BIO_set_host() | |
123 | on the BIO returned by BIO_new_ssl_connect() without having | |
124 | to locate the connect BIO first. | |
125 | ||
2c281ebb DSH |
126 | Applications do not have to call BIO_do_handshake() but may wish |
127 | to do so to separate the handshake process from other I/O | |
128 | processing. | |
129 | ||
91da5e77 RS |
130 | BIO_set_ssl(), BIO_get_ssl(), BIO_set_ssl_mode(), |
131 | BIO_set_ssl_renegotiate_bytes(), BIO_set_ssl_renegotiate_timeout(), | |
132 | BIO_get_num_renegotiates(), and BIO_do_handshake() are implemented as macros. | |
133 | ||
3ea30e76 HL |
134 | BIO_ssl_copy_session_id() is not currently supported on QUIC SSL objects. |
135 | ||
39a117d1 RS |
136 | =head1 RETURN VALUES |
137 | ||
138 | BIO_f_ssl() returns the SSL B<BIO_METHOD> structure. | |
139 | ||
140 | BIO_set_ssl(), BIO_get_ssl(), BIO_set_ssl_mode(), BIO_set_ssl_renegotiate_bytes(), | |
141 | BIO_set_ssl_renegotiate_timeout() and BIO_get_num_renegotiates() return 1 on | |
142 | success or a value which is less than or equal to 0 if an error occurred. | |
143 | ||
144 | BIO_new_ssl(), BIO_new_ssl_connect() and BIO_new_buffer_ssl_connect() return | |
145 | a valid B<BIO> structure on success or B<NULL> if an error occurred. | |
146 | ||
147 | BIO_ssl_copy_session_id() returns 1 on success or 0 on error. | |
148 | ||
149 | BIO_do_handshake() returns 1 if the connection was established successfully. | |
150 | A zero or negative value is returned if the connection could not be established. | |
151 | ||
152 | =head1 EXAMPLES | |
32751b8a | 153 | |
39a117d1 | 154 | This SSL/TLS client example attempts to retrieve a page from an |
32751b8a | 155 | SSL/TLS web server. The I/O routines are identical to those of the |
9b86974e | 156 | unencrypted example in L<BIO_s_connect(3)>. |
32751b8a DSH |
157 | |
158 | BIO *sbio, *out; | |
159 | int len; | |
160 | char tmpbuf[1024]; | |
161 | SSL_CTX *ctx; | |
162 | SSL *ssl; | |
163 | ||
05ea606a | 164 | /* XXX Seed the PRNG if needed. */ |
2c281ebb | 165 | |
a27e81ee | 166 | ctx = SSL_CTX_new(TLS_client_method()); |
32751b8a | 167 | |
05ea606a | 168 | /* XXX Set verify paths and mode here. */ |
32751b8a DSH |
169 | |
170 | sbio = BIO_new_ssl_connect(ctx); | |
32751b8a | 171 | BIO_get_ssl(sbio, &ssl); |
05ea606a RS |
172 | if (ssl == NULL) { |
173 | fprintf(stderr, "Can't locate SSL pointer\n"); | |
174 | ERR_print_errors_fp(stderr); | |
175 | exit(1); | |
32751b8a DSH |
176 | } |
177 | ||
05ea606a | 178 | /* XXX We might want to do other things with ssl here */ |
32751b8a | 179 | |
417be660 RL |
180 | /* An empty host part means the loopback address */ |
181 | BIO_set_conn_hostname(sbio, ":https"); | |
32751b8a DSH |
182 | |
183 | out = BIO_new_fp(stdout, BIO_NOCLOSE); | |
05ea606a RS |
184 | if (BIO_do_connect(sbio) <= 0) { |
185 | fprintf(stderr, "Error connecting to server\n"); | |
186 | ERR_print_errors_fp(stderr); | |
187 | exit(1); | |
2c281ebb | 188 | } |
32751b8a | 189 | |
05ea606a | 190 | /* XXX Could examine ssl here to get connection info */ |
32751b8a DSH |
191 | |
192 | BIO_puts(sbio, "GET / HTTP/1.0\n\n"); | |
2947af32 | 193 | for (;;) { |
05ea606a | 194 | len = BIO_read(sbio, tmpbuf, 1024); |
2f8e53d7 | 195 | if (len <= 0) |
05ea606a RS |
196 | break; |
197 | BIO_write(out, tmpbuf, len); | |
32751b8a DSH |
198 | } |
199 | BIO_free_all(sbio); | |
200 | BIO_free(out); | |
201 | ||
2c281ebb DSH |
202 | Here is a simple server example. It makes use of a buffering |
203 | BIO to allow lines to be read from the SSL BIO using BIO_gets. | |
204 | It creates a pseudo web page containing the actual request from | |
205 | a client and also echoes the request to standard output. | |
206 | ||
207 | BIO *sbio, *bbio, *acpt, *out; | |
208 | int len; | |
209 | char tmpbuf[1024]; | |
210 | SSL_CTX *ctx; | |
211 | SSL *ssl; | |
212 | ||
05ea606a | 213 | /* XXX Seed the PRNG if needed. */ |
2c281ebb | 214 | |
a27e81ee | 215 | ctx = SSL_CTX_new(TLS_server_method()); |
05ea606a RS |
216 | if (!SSL_CTX_use_certificate_file(ctx, "server.pem", SSL_FILETYPE_PEM) |
217 | || !SSL_CTX_use_PrivateKey_file(ctx, "server.pem", SSL_FILETYPE_PEM) | |
218 | || !SSL_CTX_check_private_key(ctx)) { | |
219 | fprintf(stderr, "Error setting up SSL_CTX\n"); | |
220 | ERR_print_errors_fp(stderr); | |
221 | exit(1); | |
2c281ebb DSH |
222 | } |
223 | ||
05ea606a | 224 | /* XXX Other things like set verify locations, EDH temp callbacks. */ |
2c281ebb DSH |
225 | |
226 | /* New SSL BIO setup as server */ | |
aebb9aac | 227 | sbio = BIO_new_ssl(ctx, 0); |
2c281ebb | 228 | BIO_get_ssl(sbio, &ssl); |
05ea606a RS |
229 | if (ssl == NULL) { |
230 | fprintf(stderr, "Can't locate SSL pointer\n"); | |
231 | ERR_print_errors_fp(stderr); | |
232 | exit(1); | |
2c281ebb DSH |
233 | } |
234 | ||
2c281ebb | 235 | bbio = BIO_new(BIO_f_buffer()); |
2c281ebb | 236 | sbio = BIO_push(bbio, sbio); |
05ea606a | 237 | acpt = BIO_new_accept("4433"); |
2c281ebb | 238 | |
05ea606a RS |
239 | /* |
240 | * By doing this when a new connection is established | |
2c281ebb DSH |
241 | * we automatically have sbio inserted into it. The |
242 | * BIO chain is now 'swallowed' by the accept BIO and | |
1bc74519 | 243 | * will be freed when the accept BIO is freed. |
2c281ebb | 244 | */ |
05ea606a | 245 | BIO_set_accept_bios(acpt, sbio); |
2c281ebb DSH |
246 | out = BIO_new_fp(stdout, BIO_NOCLOSE); |
247 | ||
47cd0e5b | 248 | /* First call to BIO_do_accept() sets up accept BIO */ |
05ea606a RS |
249 | if (BIO_do_accept(acpt) <= 0) { |
250 | fprintf(stderr, "Error setting up accept BIO\n"); | |
251 | ERR_print_errors_fp(stderr); | |
252 | exit(1); | |
2c281ebb DSH |
253 | } |
254 | ||
47cd0e5b DF |
255 | /* Second call to BIO_do_accept() waits for incoming connection */ |
256 | if (BIO_do_accept(acpt) <= 0) { | |
257 | fprintf(stderr, "Error accepting connection\n"); | |
258 | ERR_print_errors_fp(stderr); | |
259 | exit(1); | |
260 | } | |
261 | ||
05ea606a | 262 | /* We only want one connection so remove and free accept BIO */ |
2c281ebb | 263 | sbio = BIO_pop(acpt); |
2c281ebb DSH |
264 | BIO_free_all(acpt); |
265 | ||
05ea606a RS |
266 | if (BIO_do_handshake(sbio) <= 0) { |
267 | fprintf(stderr, "Error in SSL handshake\n"); | |
268 | ERR_print_errors_fp(stderr); | |
269 | exit(1); | |
2c281ebb DSH |
270 | } |
271 | ||
5ebdb390 RL |
272 | BIO_puts(sbio, "HTTP/1.0 200 OK\r\nContent-type: text/plain\r\n\r\n"); |
273 | BIO_puts(sbio, "\r\nConnection Established\r\nRequest headers:\r\n"); | |
2c281ebb DSH |
274 | BIO_puts(sbio, "--------------------------------------------------\r\n"); |
275 | ||
2947af32 | 276 | for (;;) { |
05ea606a RS |
277 | len = BIO_gets(sbio, tmpbuf, 1024); |
278 | if (len <= 0) | |
279 | break; | |
280 | BIO_write(sbio, tmpbuf, len); | |
281 | BIO_write(out, tmpbuf, len); | |
282 | /* Look for blank line signifying end of headers*/ | |
283 | if (tmpbuf[0] == '\r' || tmpbuf[0] == '\n') | |
284 | break; | |
2c281ebb DSH |
285 | } |
286 | ||
287 | BIO_puts(sbio, "--------------------------------------------------\r\n"); | |
5ebdb390 | 288 | BIO_puts(sbio, "\r\n"); |
2c281ebb | 289 | BIO_flush(sbio); |
2c281ebb DSH |
290 | BIO_free_all(sbio); |
291 | ||
e90fc053 | 292 | =head1 HISTORY |
e30dd20c | 293 | |
e90fc053 | 294 | In OpenSSL before 1.0.0 the BIO_pop() call was handled incorrectly, |
e30dd20c DSH |
295 | the I/O BIO reference count was incorrectly incremented (instead of |
296 | decremented) and dissociated with the SSL BIO even if the SSL BIO was not | |
297 | explicitly being popped (e.g. a pop higher up the chain). Applications which | |
298 | included workarounds for this bug (e.g. freeing BIOs more than once) should | |
299 | be modified to handle this fix or they may free up an already freed BIO. | |
300 | ||
e2f92610 RS |
301 | =head1 COPYRIGHT |
302 | ||
3c2bdd7d | 303 | Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 304 | |
4746f25a | 305 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
306 | this file except in compliance with the License. You can obtain a copy |
307 | in the file LICENSE in the source distribution or at | |
308 | L<https://www.openssl.org/source/license.html>. | |
309 | ||
310 | =cut |