1BIO_f_ssl(3) OpenSSL BIO_f_ssl(3)
2
6 BIO_f_ssl, BIO_set_ssl, BIO_get_ssl, BIO_set_ssl_mode,
7 BIO_set_ssl_renegotiate_bytes, BIO_get_num_renegotiates,
8 BIO_set_ssl_renegotiate_timeout, BIO_new_ssl, BIO_new_ssl_connect,
9 BIO_new_buffer_ssl_connect, BIO_ssl_copy_session_id, BIO_ssl_shutdown -
10 SSL BIO
11
13 #include <openssl/bio.h>
14 #include <openssl/ssl.h>
15 BIO_METHOD *BIO_f_ssl(void);
17 #define BIO_set_ssl(b,ssl,c) BIO_ctrl(b,BIO_C_SET_SSL,c,(char *)ssl)
19 #define BIO_get_ssl(b,sslp) BIO_ctrl(b,BIO_C_GET_SSL,0,(char *)sslp)
20 #define BIO_set_ssl_mode(b,client) BIO_ctrl(b,BIO_C_SSL_MODE,client,NULL)
21 #define BIO_set_ssl_renegotiate_bytes(b,num) \
22 BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_BYTES,num,NULL);
23 #define BIO_set_ssl_renegotiate_timeout(b,seconds) \
24 BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_TIMEOUT,seconds,NULL);
25 #define BIO_get_num_renegotiates(b) \
26 BIO_ctrl(b,BIO_C_SET_SSL_NUM_RENEGOTIATES,0,NULL);
27 BIO *BIO_new_ssl(SSL_CTX *ctx,int client);
29 BIO *BIO_new_ssl_connect(SSL_CTX *ctx);
30 BIO *BIO_new_buffer_ssl_connect(SSL_CTX *ctx);
31 int BIO_ssl_copy_session_id(BIO *to,BIO *from);
32 void BIO_ssl_shutdown(BIO *bio);
33 #define BIO_do_handshake(b) BIO_ctrl(b,BIO_C_DO_STATE_MACHINE,0,NULL)
35
37 BIO_f_ssl() returns the SSL BIO method. This is a filter BIO which is a
38 wrapper round the OpenSSL SSL routines adding a BIO "flavour" to SSL
39 I/O.
40 I/O performed on an SSL BIO communicates using the SSL protocol with
42 the SSLs read and write BIOs. If an SSL connection is not established
43 then an attempt is made to establish one on the first I/O call.
44 If a BIO is appended to an SSL BIO using BIO_push() it is automatically
46 used as the SSL BIOs read and write BIOs.
47 Calling BIO_reset() on an SSL BIO closes down any current SSL
49 connection by calling SSL_shutdown(). BIO_reset() is then sent to the
50 next BIO in the chain: this will typically disconnect the underlying
51 transport. The SSL BIO is then reset to the initial accept or connect
52 state.
53 If the close flag is set when an SSL BIO is freed then the internal SSL
55 structure is also freed using SSL_free().
56 BIO_set_ssl() sets the internal SSL pointer of BIO b to ssl using the
58 close flag c.
59 BIO_get_ssl() retrieves the SSL pointer of BIO b, it can then be
61 manipulated using the standard SSL library functions.
62 BIO_set_ssl_mode() sets the SSL BIO mode to client. If client is 1
64 client mode is set. If client is 0 server mode is set.
65 BIO_set_ssl_renegotiate_bytes() sets the renegotiate byte count to num.
67 When set after every num bytes of I/O (read and write) the SSL session
68 is automatically renegotiated. num must be at least 512 bytes.
69 BIO_set_ssl_renegotiate_timeout() sets the renegotiate timeout to
71 seconds. When the renegotiate timeout elapses the session is
72 automatically renegotiated.
73 BIO_get_num_renegotiates() returns the total number of session
75 renegotiations due to I/O or timeout.
76 BIO_new_ssl() allocates an SSL BIO using SSL_CTX ctx and using client
78 mode if client is non zero.
79 BIO_new_ssl_connect() creates a new BIO chain consisting of an SSL BIO
81 (using ctx) followed by a connect BIO.
82 BIO_new_buffer_ssl_connect() creates a new BIO chain consisting of a
84 buffering BIO, an SSL BIO (using ctx) and a connect BIO.
85 BIO_ssl_copy_session_id() copies an SSL session id between BIO chains
87 from and to. It does this by locating the SSL BIOs in each chain and
88 calling SSL_copy_session_id() on the internal SSL pointer.
89 BIO_ssl_shutdown() closes down an SSL connection on BIO chain bio. It
91 does this by locating the SSL BIO in the chain and calling
92 SSL_shutdown() on its internal SSL pointer.
93 BIO_do_handshake() attempts to complete an SSL handshake on the
95 supplied BIO and establish the SSL connection. It returns 1 if the
96 connection was established successfully. A zero or negative value is
97 returned if the connection could not be established, the call
98 BIO_should_retry() should be used for non blocking connect BIOs to
99 determine if the call should be retried. If an SSL connection has
100 already been established this call has no effect.
101
103 SSL BIOs are exceptional in that if the underlying transport is non
104 blocking they can still request a retry in exceptional circumstances.
105 Specifically this will happen if a session renegotiation takes place
106 during a BIO_read() operation, one case where this happens is when SGC
107 or step up occurs.
108 In OpenSSL 0.9.6 and later the SSL flag SSL_AUTO_RETRY can be set to
110 disable this behaviour. That is when this flag is set an SSL BIO using
111 a blocking transport will never request a retry.
112 Since unknown BIO_ctrl() operations are sent through filter BIOs the
114 servers name and port can be set using BIO_set_host() on the BIO
115 returned by BIO_new_ssl_connect() without having to locate the connect
116 BIO first.
117 Applications do not have to call BIO_do_handshake() but may wish to do
119 so to separate the handshake process from other I/O processing.
120
122 TBA
123
125 This SSL/TLS client example, attempts to retrieve a page from an
126 SSL/TLS web server. The I/O routines are identical to those of the
127 unencrypted example in BIO_s_connect(3).
128 BIO *sbio, *out;
130 int len;
131 char tmpbuf[1024];
132 SSL_CTX *ctx;
133 SSL *ssl;
134 ERR_load_crypto_strings();
136 ERR_load_SSL_strings();
137 OpenSSL_add_all_algorithms();
138 /* We would seed the PRNG here if the platform didn't
140 * do it automatically
141 */
142 ctx = SSL_CTX_new(SSLv23_client_method());
144 /* We'd normally set some stuff like the verify paths and
146 * mode here because as things stand this will connect to
147 * any server whose certificate is signed by any CA.
148 */
149 sbio = BIO_new_ssl_connect(ctx);
151 BIO_get_ssl(sbio, &ssl);
153 if(!ssl) {
155 fprintf(stderr, "Can't locate SSL pointer\n");
156 /* whatever ... */
157 }
158 /* Don't want any retries */
160 SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY);
161 /* We might want to do other things with ssl here */
163 BIO_set_conn_hostname(sbio, "localhost:https");
165 out = BIO_new_fp(stdout, BIO_NOCLOSE);
167 if(BIO_do_connect(sbio) <= 0) {
168 fprintf(stderr, "Error connecting to server\n");
169 ERR_print_errors_fp(stderr);
170 /* whatever ... */
171 }
172 if(BIO_do_handshake(sbio) <= 0) {
174 fprintf(stderr, "Error establishing SSL connection\n");
175 ERR_print_errors_fp(stderr);
176 /* whatever ... */
177 }
178 /* Could examine ssl here to get connection info */
180 BIO_puts(sbio, "GET / HTTP/1.0\n\n");
182 for(;;) {
183 len = BIO_read(sbio, tmpbuf, 1024);
184 if(len <= 0) break;
185 BIO_write(out, tmpbuf, len);
186 }
187 BIO_free_all(sbio);
188 BIO_free(out);
189 Here is a simple server example. It makes use of a buffering BIO to
191 allow lines to be read from the SSL BIO using BIO_gets. It creates a
192 pseudo web page containing the actual request from a client and also
193 echoes the request to standard output.
194 BIO *sbio, *bbio, *acpt, *out;
196 int len;
197 char tmpbuf[1024];
198 SSL_CTX *ctx;
199 SSL *ssl;
200 ERR_load_crypto_strings();
202 ERR_load_SSL_strings();
203 OpenSSL_add_all_algorithms();
204 /* Might seed PRNG here */
206 ctx = SSL_CTX_new(SSLv23_server_method());
208 if (!SSL_CTX_use_certificate_file(ctx,"server.pem",SSL_FILETYPE_PEM)
210 || !SSL_CTX_use_PrivateKey_file(ctx,"server.pem",SSL_FILETYPE_PEM)
211 || !SSL_CTX_check_private_key(ctx)) {
212 fprintf(stderr, "Error setting up SSL_CTX\n");
214 ERR_print_errors_fp(stderr);
215 return 0;
216 }
217 /* Might do other things here like setting verify locations and
219 * DH and/or RSA temporary key callbacks
220 */
221 /* New SSL BIO setup as server */
223 sbio=BIO_new_ssl(ctx,0);
224 BIO_get_ssl(sbio, &ssl);
226 if(!ssl) {
228 fprintf(stderr, "Can't locate SSL pointer\n");
229 /* whatever ... */
230 }
231 /* Don't want any retries */
233 SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY);
234 /* Create the buffering BIO */
236 bbio = BIO_new(BIO_f_buffer());
238 /* Add to chain */
240 sbio = BIO_push(bbio, sbio);
241 acpt=BIO_new_accept("4433");
243 /* By doing this when a new connection is established
245 * we automatically have sbio inserted into it. The
246 * BIO chain is now 'swallowed' by the accept BIO and
247 * will be freed when the accept BIO is freed.
248 */
249 BIO_set_accept_bios(acpt,sbio);
251 out = BIO_new_fp(stdout, BIO_NOCLOSE);
253 /* Setup accept BIO */
255 if(BIO_do_accept(acpt) <= 0) {
256 fprintf(stderr, "Error setting up accept BIO\n");
257 ERR_print_errors_fp(stderr);
258 return 0;
259 }
260 /* Now wait for incoming connection */
262 if(BIO_do_accept(acpt) <= 0) {
263 fprintf(stderr, "Error in connection\n");
264 ERR_print_errors_fp(stderr);
265 return 0;
266 }
267 /* We only want one connection so remove and free
269 * accept BIO
270 */
271 sbio = BIO_pop(acpt);
273 BIO_free_all(acpt);
275 if(BIO_do_handshake(sbio) <= 0) {
277 fprintf(stderr, "Error in SSL handshake\n");
278 ERR_print_errors_fp(stderr);
279 return 0;
280 }
281 BIO_puts(sbio, "HTTP/1.0 200 OK\r\nContent-type: text/plain\r\n\r\n");
283 BIO_puts(sbio, "\r\nConnection Established\r\nRequest headers:\r\n");
284 BIO_puts(sbio, "--------------------------------------------------\r\n");
285 for(;;) {
287 len = BIO_gets(sbio, tmpbuf, 1024);
288 if(len <= 0) break;
289 BIO_write(sbio, tmpbuf, len);
290 BIO_write(out, tmpbuf, len);
291 /* Look for blank line signifying end of headers*/
292 if((tmpbuf[0] == '\r') || (tmpbuf[0] == '\n')) break;
293 }
294 BIO_puts(sbio, "--------------------------------------------------\r\n");
296 BIO_puts(sbio, "\r\n");
297 /* Since there is a buffering BIO present we had better flush it */
299 BIO_flush(sbio);
300 BIO_free_all(sbio);
302
304 In OpenSSL versions before 1.0.0 the BIO_pop() call was handled
305 incorrectly, the I/O BIO reference count was incorrectly incremented
306 (instead of decremented) and dissociated with the SSL BIO even if the
307 SSL BIO was not explicitly being popped (e.g. a pop higher up the
308 chain). Applications which included workarounds for this bug (e.g.
309 freeing BIOs more than once) should be modified to handle this fix or
310 they may free up an already freed BIO.
311
313 TBA
3141.0.1e 2013-02-11 BIO_f_ssl(3)