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