168651Skris=pod 268651Skris 368651Skris=head1 NAME 468651Skris 568651SkrisBIO_f_ssl, BIO_set_ssl, BIO_get_ssl, BIO_set_ssl_mode, BIO_set_ssl_renegotiate_bytes, 668651SkrisBIO_get_num_renegotiates, BIO_set_ssl_renegotiate_timeout, BIO_new_ssl, 768651SkrisBIO_new_ssl_connect, BIO_new_buffer_ssl_connect, BIO_ssl_copy_session_id, 868651SkrisBIO_ssl_shutdown - SSL BIO 968651Skris 1068651Skris=head1 SYNOPSIS 1168651Skris 1268651Skris #include <openssl/bio.h> 1368651Skris #include <openssl/ssl.h> 1468651Skris 1568651Skris BIO_METHOD *BIO_f_ssl(void); 1668651Skris 1768651Skris #define BIO_set_ssl(b,ssl,c) BIO_ctrl(b,BIO_C_SET_SSL,c,(char *)ssl) 1868651Skris #define BIO_get_ssl(b,sslp) BIO_ctrl(b,BIO_C_GET_SSL,0,(char *)sslp) 1968651Skris #define BIO_set_ssl_mode(b,client) BIO_ctrl(b,BIO_C_SSL_MODE,client,NULL) 2068651Skris #define BIO_set_ssl_renegotiate_bytes(b,num) \ 2168651Skris BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_BYTES,num,NULL); 2268651Skris #define BIO_set_ssl_renegotiate_timeout(b,seconds) \ 2368651Skris BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_TIMEOUT,seconds,NULL); 2468651Skris #define BIO_get_num_renegotiates(b) \ 2568651Skris BIO_ctrl(b,BIO_C_SET_SSL_NUM_RENEGOTIATES,0,NULL); 2668651Skris 2768651Skris BIO *BIO_new_ssl(SSL_CTX *ctx,int client); 2868651Skris BIO *BIO_new_ssl_connect(SSL_CTX *ctx); 2968651Skris BIO *BIO_new_buffer_ssl_connect(SSL_CTX *ctx); 3068651Skris int BIO_ssl_copy_session_id(BIO *to,BIO *from); 3168651Skris void BIO_ssl_shutdown(BIO *bio); 3268651Skris 3368651Skris #define BIO_do_handshake(b) BIO_ctrl(b,BIO_C_DO_STATE_MACHINE,0,NULL) 3468651Skris 3568651Skris=head1 DESCRIPTION 3668651Skris 3768651SkrisBIO_f_ssl() returns the SSL BIO method. This is a filter BIO which 3868651Skrisis a wrapper round the OpenSSL SSL routines adding a BIO "flavour" to 3968651SkrisSSL I/O. 4068651Skris 4168651SkrisI/O performed on an SSL BIO communicates using the SSL protocol with 4268651Skristhe SSLs read and write BIOs. If an SSL connection is not established 4368651Skristhen an attempt is made to establish one on the first I/O call. 4468651Skris 4568651SkrisIf a BIO is appended to an SSL BIO using BIO_push() it is automatically 4668651Skrisused as the SSL BIOs read and write BIOs. 4768651Skris 4868651SkrisCalling BIO_reset() on an SSL BIO closes down any current SSL connection 4968651Skrisby calling SSL_shutdown(). BIO_reset() is then sent to the next BIO in 5068651Skristhe chain: this will typically disconnect the underlying transport. 5168651SkrisThe SSL BIO is then reset to the initial accept or connect state. 5268651Skris 5368651SkrisIf the close flag is set when an SSL BIO is freed then the internal 5468651SkrisSSL structure is also freed using SSL_free(). 5568651Skris 5668651SkrisBIO_set_ssl() sets the internal SSL pointer of BIO B<b> to B<ssl> using 5768651Skristhe close flag B<c>. 5868651Skris 5968651SkrisBIO_get_ssl() retrieves the SSL pointer of BIO B<b>, it can then be 6068651Skrismanipulated using the standard SSL library functions. 6168651Skris 6268651SkrisBIO_set_ssl_mode() sets the SSL BIO mode to B<client>. If B<client> 6368651Skrisis 1 client mode is set. If B<client> is 0 server mode is set. 6468651Skris 6568651SkrisBIO_set_ssl_renegotiate_bytes() sets the renegotiate byte count 6668651Skristo B<num>. When set after every B<num> bytes of I/O (read and write) 6768651Skristhe SSL session is automatically renegotiated. B<num> must be at 6868651Skrisleast 512 bytes. 6968651Skris 7068651SkrisBIO_set_ssl_renegotiate_timeout() sets the renegotiate timeout to 7168651SkrisB<seconds>. When the renegotiate timeout elapses the session is 7268651Skrisautomatically renegotiated. 7368651Skris 7468651SkrisBIO_get_num_renegotiates() returns the total number of session 7568651Skrisrenegotiations due to I/O or timeout. 7668651Skris 7768651SkrisBIO_new_ssl() allocates an SSL BIO using SSL_CTX B<ctx> and using 7868651Skrisclient mode if B<client> is non zero. 7968651Skris 8068651SkrisBIO_new_ssl_connect() creates a new BIO chain consisting of an 8168651SkrisSSL BIO (using B<ctx>) followed by a connect BIO. 8268651Skris 8368651SkrisBIO_new_buffer_ssl_connect() creates a new BIO chain consisting 8468651Skrisof a buffering BIO, an SSL BIO (using B<ctx>) and a connect 8568651SkrisBIO. 8668651Skris 8768651SkrisBIO_ssl_copy_session_id() copies an SSL session id between 8868651SkrisBIO chains B<from> and B<to>. It does this by locating the 8968651SkrisSSL BIOs in each chain and calling SSL_copy_session_id() on 9068651Skristhe internal SSL pointer. 9168651Skris 9268651SkrisBIO_ssl_shutdown() closes down an SSL connection on BIO 9368651Skrischain B<bio>. It does this by locating the SSL BIO in the 9468651Skrischain and calling SSL_shutdown() on its internal SSL 9568651Skrispointer. 9668651Skris 9768651SkrisBIO_do_handshake() attempts to complete an SSL handshake on the 9868651Skrissupplied BIO and establish the SSL connection. It returns 1 9968651Skrisif the connection was established successfully. A zero or negative 10068651Skrisvalue is returned if the connection could not be established, the 10168651Skriscall BIO_should_retry() should be used for non blocking connect BIOs 10268651Skristo determine if the call should be retried. If an SSL connection has 10368651Skrisalready been established this call has no effect. 10468651Skris 10568651Skris=head1 NOTES 10668651Skris 10768651SkrisSSL BIOs are exceptional in that if the underlying transport 10868651Skrisis non blocking they can still request a retry in exceptional 10968651Skriscircumstances. Specifically this will happen if a session 11068651Skrisrenegotiation takes place during a BIO_read() operation, one 11168651Skriscase where this happens is when SGC or step up occurs. 11268651Skris 11368651SkrisIn OpenSSL 0.9.6 and later the SSL flag SSL_AUTO_RETRY can be 11468651Skrisset to disable this behaviour. That is when this flag is set 11568651Skrisan SSL BIO using a blocking transport will never request a 11668651Skrisretry. 11768651Skris 11868651SkrisSince unknown BIO_ctrl() operations are sent through filter 11968651SkrisBIOs the servers name and port can be set using BIO_set_host() 12068651Skrison the BIO returned by BIO_new_ssl_connect() without having 12168651Skristo locate the connect BIO first. 12268651Skris 12368651SkrisApplications do not have to call BIO_do_handshake() but may wish 12468651Skristo do so to separate the handshake process from other I/O 12568651Skrisprocessing. 12668651Skris 12768651Skris=head1 RETURN VALUES 12868651Skris 12968651SkrisTBA 13068651Skris 13168651Skris=head1 EXAMPLE 13268651Skris 13368651SkrisThis SSL/TLS client example, attempts to retrieve a page from an 13468651SkrisSSL/TLS web server. The I/O routines are identical to those of the 13568651Skrisunencrypted example in L<BIO_s_connect(3)|BIO_s_connect(3)>. 13668651Skris 13768651Skris BIO *sbio, *out; 13868651Skris int len; 13968651Skris char tmpbuf[1024]; 14068651Skris SSL_CTX *ctx; 14168651Skris SSL *ssl; 14268651Skris 14368651Skris ERR_load_crypto_strings(); 14468651Skris ERR_load_SSL_strings(); 14568651Skris OpenSSL_add_all_algorithms(); 14668651Skris 14768651Skris /* We would seed the PRNG here if the platform didn't 14868651Skris * do it automatically 14968651Skris */ 15068651Skris 15168651Skris ctx = SSL_CTX_new(SSLv23_client_method()); 15268651Skris 15368651Skris /* We'd normally set some stuff like the verify paths and 15468651Skris * mode here because as things stand this will connect to 15568651Skris * any server whose certificate is signed by any CA. 15668651Skris */ 15768651Skris 15868651Skris sbio = BIO_new_ssl_connect(ctx); 15968651Skris 16068651Skris BIO_get_ssl(sbio, &ssl); 16168651Skris 16268651Skris if(!ssl) { 16368651Skris fprintf(stderr, "Can't locate SSL pointer\n"); 16468651Skris /* whatever ... */ 16568651Skris } 16668651Skris 16768651Skris /* Don't want any retries */ 16868651Skris SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY); 16968651Skris 17068651Skris /* We might want to do other things with ssl here */ 17168651Skris 17268651Skris BIO_set_conn_hostname(sbio, "localhost:https"); 17368651Skris 17468651Skris out = BIO_new_fp(stdout, BIO_NOCLOSE); 17568651Skris if(BIO_do_connect(sbio) <= 0) { 17668651Skris fprintf(stderr, "Error connecting to server\n"); 17768651Skris ERR_print_errors_fp(stderr); 17868651Skris /* whatever ... */ 17968651Skris } 18068651Skris 18168651Skris if(BIO_do_handshake(sbio) <= 0) { 18268651Skris fprintf(stderr, "Error establishing SSL connection\n"); 18368651Skris ERR_print_errors_fp(stderr); 18468651Skris /* whatever ... */ 18568651Skris } 18668651Skris 18768651Skris /* Could examine ssl here to get connection info */ 18868651Skris 18968651Skris BIO_puts(sbio, "GET / HTTP/1.0\n\n"); 19068651Skris for(;;) { 19168651Skris len = BIO_read(sbio, tmpbuf, 1024); 19268651Skris if(len <= 0) break; 19368651Skris BIO_write(out, tmpbuf, len); 19468651Skris } 19568651Skris BIO_free_all(sbio); 19668651Skris BIO_free(out); 19768651Skris 19868651SkrisHere is a simple server example. It makes use of a buffering 19968651SkrisBIO to allow lines to be read from the SSL BIO using BIO_gets. 20068651SkrisIt creates a pseudo web page containing the actual request from 20168651Skrisa client and also echoes the request to standard output. 20268651Skris 20368651Skris BIO *sbio, *bbio, *acpt, *out; 20468651Skris int len; 20568651Skris char tmpbuf[1024]; 20668651Skris SSL_CTX *ctx; 20768651Skris SSL *ssl; 20868651Skris 20968651Skris ERR_load_crypto_strings(); 21068651Skris ERR_load_SSL_strings(); 21168651Skris OpenSSL_add_all_algorithms(); 21268651Skris 21368651Skris /* Might seed PRNG here */ 21468651Skris 21568651Skris ctx = SSL_CTX_new(SSLv23_server_method()); 21668651Skris 21768651Skris if (!SSL_CTX_use_certificate_file(ctx,"server.pem",SSL_FILETYPE_PEM) 21868651Skris || !SSL_CTX_use_PrivateKey_file(ctx,"server.pem",SSL_FILETYPE_PEM) 21968651Skris || !SSL_CTX_check_private_key(ctx)) { 22068651Skris 22168651Skris fprintf(stderr, "Error setting up SSL_CTX\n"); 22268651Skris ERR_print_errors_fp(stderr); 22368651Skris return 0; 22468651Skris } 22568651Skris 22668651Skris /* Might do other things here like setting verify locations and 22768651Skris * DH and/or RSA temporary key callbacks 22868651Skris */ 22968651Skris 23068651Skris /* New SSL BIO setup as server */ 23168651Skris sbio=BIO_new_ssl(ctx,0); 23268651Skris 23368651Skris BIO_get_ssl(sbio, &ssl); 23468651Skris 23568651Skris if(!ssl) { 23668651Skris fprintf(stderr, "Can't locate SSL pointer\n"); 23768651Skris /* whatever ... */ 23868651Skris } 23968651Skris 24068651Skris /* Don't want any retries */ 24168651Skris SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY); 24268651Skris 24368651Skris /* Create the buffering BIO */ 24468651Skris 24568651Skris bbio = BIO_new(BIO_f_buffer()); 24668651Skris 24768651Skris /* Add to chain */ 24868651Skris sbio = BIO_push(bbio, sbio); 24968651Skris 25068651Skris acpt=BIO_new_accept("4433"); 25168651Skris 25268651Skris /* By doing this when a new connection is established 25368651Skris * we automatically have sbio inserted into it. The 25468651Skris * BIO chain is now 'swallowed' by the accept BIO and 25568651Skris * will be freed when the accept BIO is freed. 25668651Skris */ 25768651Skris 25868651Skris BIO_set_accept_bios(acpt,sbio); 25968651Skris 26068651Skris out = BIO_new_fp(stdout, BIO_NOCLOSE); 26168651Skris 26268651Skris /* Setup accept BIO */ 26368651Skris if(BIO_do_accept(acpt) <= 0) { 26468651Skris fprintf(stderr, "Error setting up accept BIO\n"); 26568651Skris ERR_print_errors_fp(stderr); 26668651Skris return 0; 26768651Skris } 26868651Skris 26968651Skris /* Now wait for incoming connection */ 27068651Skris if(BIO_do_accept(acpt) <= 0) { 27168651Skris fprintf(stderr, "Error in connection\n"); 27268651Skris ERR_print_errors_fp(stderr); 27368651Skris return 0; 27468651Skris } 27568651Skris 27668651Skris /* We only want one connection so remove and free 27768651Skris * accept BIO 27868651Skris */ 27968651Skris 28068651Skris sbio = BIO_pop(acpt); 28168651Skris 28268651Skris BIO_free_all(acpt); 28368651Skris 28468651Skris if(BIO_do_handshake(sbio) <= 0) { 28568651Skris fprintf(stderr, "Error in SSL handshake\n"); 28668651Skris ERR_print_errors_fp(stderr); 28768651Skris return 0; 28868651Skris } 28968651Skris 290127128Snectar BIO_puts(sbio, "HTTP/1.0 200 OK\r\nContent-type: text/plain\r\n\r\n"); 291127128Snectar BIO_puts(sbio, "\r\nConnection Established\r\nRequest headers:\r\n"); 29268651Skris BIO_puts(sbio, "--------------------------------------------------\r\n"); 29368651Skris 29468651Skris for(;;) { 29568651Skris len = BIO_gets(sbio, tmpbuf, 1024); 29668651Skris if(len <= 0) break; 29768651Skris BIO_write(sbio, tmpbuf, len); 29868651Skris BIO_write(out, tmpbuf, len); 29968651Skris /* Look for blank line signifying end of headers*/ 30068651Skris if((tmpbuf[0] == '\r') || (tmpbuf[0] == '\n')) break; 30168651Skris } 30268651Skris 30368651Skris BIO_puts(sbio, "--------------------------------------------------\r\n"); 304127128Snectar BIO_puts(sbio, "\r\n"); 30568651Skris 30668651Skris /* Since there is a buffering BIO present we had better flush it */ 30768651Skris BIO_flush(sbio); 30868651Skris 30968651Skris BIO_free_all(sbio); 31068651Skris 311238405Sjkim=head1 BUGS 312238405Sjkim 313238405SjkimIn OpenSSL versions before 1.0.0 the BIO_pop() call was handled incorrectly, 314238405Sjkimthe I/O BIO reference count was incorrectly incremented (instead of 315238405Sjkimdecremented) and dissociated with the SSL BIO even if the SSL BIO was not 316238405Sjkimexplicitly being popped (e.g. a pop higher up the chain). Applications which 317238405Sjkimincluded workarounds for this bug (e.g. freeing BIOs more than once) should 318238405Sjkimbe modified to handle this fix or they may free up an already freed BIO. 319238405Sjkim 32068651Skris=head1 SEE ALSO 32168651Skris 32268651SkrisTBA 323