1BIO_f_ssl(3)                        OpenSSL                       BIO_f_ssl(3)
2
3
4

NAME

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

SYNOPSIS

13        #include <openssl/bio.h>
14        #include <openssl/ssl.h>
15
16        BIO_METHOD *BIO_f_ssl(void);
17
18        #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
28        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
34        #define BIO_do_handshake(b)    BIO_ctrl(b,BIO_C_DO_STATE_MACHINE,0,NULL)
35

DESCRIPTION

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
41       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
45       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
48       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
54       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
57       BIO_set_ssl() sets the internal SSL pointer of BIO b to ssl using the
58       close flag c.
59
60       BIO_get_ssl() retrieves the SSL pointer of BIO b, it can then be
61       manipulated using the standard SSL library functions.
62
63       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
66       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
70       BIO_set_ssl_renegotiate_timeout() sets the renegotiate timeout to
71       seconds. When the renegotiate timeout elapses the session is
72       automatically renegotiated.
73
74       BIO_get_num_renegotiates() returns the total number of session
75       renegotiations due to I/O or timeout.
76
77       BIO_new_ssl() allocates an SSL BIO using SSL_CTX ctx and using client
78       mode if client is non zero.
79
80       BIO_new_ssl_connect() creates a new BIO chain consisting of an SSL BIO
81       (using ctx) followed by a connect BIO.
82
83       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
86       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
90       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
94       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

NOTES

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 step
107       up occurs.
108
109       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
113       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
118       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

RETURN VALUES

122       TBA
123

EXAMPLE

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
129        BIO *sbio, *out;
130        int len;
131        char tmpbuf[1024];
132        SSL_CTX *ctx;
133        SSL *ssl;
134
135        ERR_load_crypto_strings();
136        ERR_load_SSL_strings();
137        OpenSSL_add_all_algorithms();
138
139        /* We would seed the PRNG here if the platform didn't
140         * do it automatically
141         */
142
143        ctx = SSL_CTX_new(SSLv23_client_method());
144
145        /* 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
150        sbio = BIO_new_ssl_connect(ctx);
151
152        BIO_get_ssl(sbio, &ssl);
153
154        if(!ssl) {
155          fprintf(stderr, "Can't locate SSL pointer\n");
156          /* whatever ... */
157        }
158
159        /* Don't want any retries */
160        SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY);
161
162        /* We might want to do other things with ssl here */
163
164        BIO_set_conn_hostname(sbio, "localhost:https");
165
166        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
173        if(BIO_do_handshake(sbio) <= 0) {
174               fprintf(stderr, "Error establishing SSL connection\n");
175               ERR_print_errors_fp(stderr);
176               /* whatever ... */
177        }
178
179        /* Could examine ssl here to get connection info */
180
181        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
190       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
195        BIO *sbio, *bbio, *acpt, *out;
196        int len;
197        char tmpbuf[1024];
198        SSL_CTX *ctx;
199        SSL *ssl;
200
201        ERR_load_crypto_strings();
202        ERR_load_SSL_strings();
203        OpenSSL_add_all_algorithms();
204
205        /* Might seed PRNG here */
206
207        ctx = SSL_CTX_new(SSLv23_server_method());
208
209        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
213               fprintf(stderr, "Error setting up SSL_CTX\n");
214               ERR_print_errors_fp(stderr);
215               return 0;
216        }
217
218        /* Might do other things here like setting verify locations and
219         * DH and/or RSA temporary key callbacks
220         */
221
222        /* New SSL BIO setup as server */
223        sbio=BIO_new_ssl(ctx,0);
224
225        BIO_get_ssl(sbio, &ssl);
226
227        if(!ssl) {
228          fprintf(stderr, "Can't locate SSL pointer\n");
229          /* whatever ... */
230        }
231
232        /* Don't want any retries */
233        SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY);
234
235        /* Create the buffering BIO */
236
237        bbio = BIO_new(BIO_f_buffer());
238
239        /* Add to chain */
240        sbio = BIO_push(bbio, sbio);
241
242        acpt=BIO_new_accept("4433");
243
244        /* 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
250        BIO_set_accept_bios(acpt,sbio);
251
252        out = BIO_new_fp(stdout, BIO_NOCLOSE);
253
254        /* 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
261        /* 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
268        /* We only want one connection so remove and free
269         * accept BIO
270         */
271
272        sbio = BIO_pop(acpt);
273
274        BIO_free_all(acpt);
275
276        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
282        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
286        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
295        BIO_puts(sbio, "--------------------------------------------------\r\n");
296        BIO_puts(sbio, "\r\n");
297
298        /* Since there is a buffering BIO present we had better flush it */
299        BIO_flush(sbio);
300
301        BIO_free_all(sbio);
302

BUGS

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

SEE ALSO

313       TBA
314
315
316
3171.0.2k                            2017-01-26                      BIO_f_ssl(3)
Impressum