=head1 NAME
-BIO_f_ssl, BIO_set_ssl, BIO_get_ssl, BIO_set_ssl_mode, BIO_set_ssl_renegotiate_bytes,
+BIO_do_handshake,
+BIO_f_ssl, BIO_set_ssl, BIO_get_ssl, BIO_set_ssl_mode,
+BIO_set_ssl_renegotiate_bytes,
BIO_get_num_renegotiates, BIO_set_ssl_renegotiate_timeout, BIO_new_ssl,
BIO_new_ssl_connect, BIO_new_buffer_ssl_connect, BIO_ssl_copy_session_id,
BIO_ssl_shutdown - SSL BIO
+=for comment multiple includes
+
=head1 SYNOPSIS
#include <openssl/bio.h>
#include <openssl/ssl.h>
- BIO_METHOD *BIO_f_ssl(void);
+ const BIO_METHOD *BIO_f_ssl(void);
- #define BIO_set_ssl(b,ssl,c) BIO_ctrl(b,BIO_C_SET_SSL,c,(char *)ssl)
- #define BIO_get_ssl(b,sslp) BIO_ctrl(b,BIO_C_GET_SSL,0,(char *)sslp)
- #define BIO_set_ssl_mode(b,client) BIO_ctrl(b,BIO_C_SSL_MODE,client,NULL)
- #define BIO_set_ssl_renegotiate_bytes(b,num) \
- BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_BYTES,num,NULL);
- #define BIO_set_ssl_renegotiate_timeout(b,seconds) \
- BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_TIMEOUT,seconds,NULL);
- #define BIO_get_num_renegotiates(b) \
- BIO_ctrl(b,BIO_C_SET_SSL_NUM_RENEGOTIATES,0,NULL);
+ long BIO_set_ssl(BIO *b, SSL *ssl, long c);
+ long BIO_get_ssl(BIO *b, SSL **sslp);
+ long BIO_set_ssl_mode(BIO *b, long client);
+ long BIO_set_ssl_renegotiate_bytes(BIO *b, long num);
+ long BIO_set_ssl_renegotiate_timeout(BIO *b, long seconds);
+ long BIO_get_num_renegotiates(BIO *b);
- BIO *BIO_new_ssl(SSL_CTX *ctx,int client);
+ BIO *BIO_new_ssl(SSL_CTX *ctx, int client);
BIO *BIO_new_ssl_connect(SSL_CTX *ctx);
BIO *BIO_new_buffer_ssl_connect(SSL_CTX *ctx);
- int BIO_ssl_copy_session_id(BIO *to,BIO *from);
+ int BIO_ssl_copy_session_id(BIO *to, BIO *from);
void BIO_ssl_shutdown(BIO *bio);
- #define BIO_do_handshake(b) BIO_ctrl(b,BIO_C_DO_STATE_MACHINE,0,NULL)
+ long BIO_do_handshake(BIO *b);
=head1 DESCRIPTION
BIO_f_ssl() returns the SSL BIO method. This is a filter BIO which
is a wrapper round the OpenSSL SSL routines adding a BIO "flavour" to
-SSL I/O.
+SSL I/O.
I/O performed on an SSL BIO communicates using the SSL protocol with
the SSLs read and write BIOs. If an SSL connection is not established
is 1 client mode is set. If B<client> is 0 server mode is set.
BIO_set_ssl_renegotiate_bytes() sets the renegotiate byte count
-to B<num>. When set after every B<num> bytes of I/O (read and write)
+to B<num>. When set after every B<num> bytes of I/O (read and write)
the SSL session is automatically renegotiated. B<num> must be at
least 512 bytes.
of a buffering BIO, an SSL BIO (using B<ctx>) and a connect
BIO.
-BIO_ssl_copy_session_id() copies an SSL session id between
+BIO_ssl_copy_session_id() copies an SSL session id between
BIO chains B<from> and B<to>. It does this by locating the
SSL BIOs in each chain and calling SSL_copy_session_id() on
the internal SSL pointer.
is non blocking they can still request a retry in exceptional
circumstances. Specifically this will happen if a session
renegotiation takes place during a BIO_read() operation, one
-case where this happens is when SGC or step up occurs.
+case where this happens is when step up occurs.
-In OpenSSL 0.9.6 and later the SSL flag SSL_AUTO_RETRY can be
+The SSL flag SSL_AUTO_RETRY can be
set to disable this behaviour. That is when this flag is set
an SSL BIO using a blocking transport will never request a
retry.
to do so to separate the handshake process from other I/O
processing.
-=head1 RETURN VALUES
-
-TBA
+BIO_set_ssl(), BIO_get_ssl(), BIO_set_ssl_mode(),
+BIO_set_ssl_renegotiate_bytes(), BIO_set_ssl_renegotiate_timeout(),
+BIO_get_num_renegotiates(), and BIO_do_handshake() are implemented as macros.
=head1 EXAMPLE
This SSL/TLS client example, attempts to retrieve a page from an
SSL/TLS web server. The I/O routines are identical to those of the
-unencrypted example in L<BIO_s_connect(3)|BIO_s_connect(3)>.
+unencrypted example in L<BIO_s_connect(3)>.
BIO *sbio, *out;
int len;
SSL_CTX *ctx;
SSL *ssl;
- ERR_load_crypto_strings();
- ERR_load_SSL_strings();
- OpenSSL_add_all_algorithms();
-
- /* We would seed the PRNG here if the platform didn't
- * do it automatically
- */
+ /* XXX Seed the PRNG if needed. */
- ctx = SSL_CTX_new(SSLv23_client_method());
+ ctx = SSL_CTX_new(TLS_client_method());
- /* We'd normally set some stuff like the verify paths and
- * mode here because as things stand this will connect to
- * any server whose certificate is signed by any CA.
- */
+ /* XXX Set verify paths and mode here. */
sbio = BIO_new_ssl_connect(ctx);
-
BIO_get_ssl(sbio, &ssl);
-
- if(!ssl) {
- fprintf(stderr, "Can't locate SSL pointer\n");
- /* whatever ... */
+ if (ssl == NULL) {
+ fprintf(stderr, "Can't locate SSL pointer\n");
+ ERR_print_errors_fp(stderr);
+ exit(1);
}
/* Don't want any retries */
SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY);
- /* We might want to do other things with ssl here */
+ /* XXX We might want to do other things with ssl here */
- BIO_set_conn_hostname(sbio, "localhost:https");
+ /* An empty host part means the loopback address */
+ BIO_set_conn_hostname(sbio, ":https");
out = BIO_new_fp(stdout, BIO_NOCLOSE);
- if(BIO_do_connect(sbio) <= 0) {
- fprintf(stderr, "Error connecting to server\n");
- ERR_print_errors_fp(stderr);
- /* whatever ... */
+ if (BIO_do_connect(sbio) <= 0) {
+ fprintf(stderr, "Error connecting to server\n");
+ ERR_print_errors_fp(stderr);
+ exit(1);
}
-
- if(BIO_do_handshake(sbio) <= 0) {
- fprintf(stderr, "Error establishing SSL connection\n");
- ERR_print_errors_fp(stderr);
- /* whatever ... */
+ if (BIO_do_handshake(sbio) <= 0) {
+ fprintf(stderr, "Error establishing SSL connection\n");
+ ERR_print_errors_fp(stderr);
+ exit(1);
}
- /* Could examine ssl here to get connection info */
+ /* XXX Could examine ssl here to get connection info */
BIO_puts(sbio, "GET / HTTP/1.0\n\n");
- for(;;) {
- len = BIO_read(sbio, tmpbuf, 1024);
- if(len <= 0) break;
- BIO_write(out, tmpbuf, len);
+ for ( ; ; ) {
+ len = BIO_read(sbio, tmpbuf, 1024);
+ if (len <= 0)
+ break;
+ BIO_write(out, tmpbuf, len);
}
BIO_free_all(sbio);
BIO_free(out);
SSL_CTX *ctx;
SSL *ssl;
- ERR_load_crypto_strings();
- ERR_load_SSL_strings();
- OpenSSL_add_all_algorithms();
+ /* XXX Seed the PRNG if needed. */
- /* Might seed PRNG here */
-
- ctx = SSL_CTX_new(SSLv23_server_method());
-
- if (!SSL_CTX_use_certificate_file(ctx,"server.pem",SSL_FILETYPE_PEM)
- || !SSL_CTX_use_PrivateKey_file(ctx,"server.pem",SSL_FILETYPE_PEM)
- || !SSL_CTX_check_private_key(ctx)) {
-
- fprintf(stderr, "Error setting up SSL_CTX\n");
- ERR_print_errors_fp(stderr);
- return 0;
+ ctx = SSL_CTX_new(TLS_server_method());
+ if (!SSL_CTX_use_certificate_file(ctx, "server.pem", SSL_FILETYPE_PEM)
+ || !SSL_CTX_use_PrivateKey_file(ctx, "server.pem", SSL_FILETYPE_PEM)
+ || !SSL_CTX_check_private_key(ctx)) {
+ fprintf(stderr, "Error setting up SSL_CTX\n");
+ ERR_print_errors_fp(stderr);
+ exit(1);
}
- /* Might do other things here like setting verify locations and
- * DH and/or RSA temporary key callbacks
- */
+ /* XXX Other things like set verify locations, EDH temp callbacks. */
/* New SSL BIO setup as server */
- sbio=BIO_new_ssl(ctx,0);
-
+ sbio = BIO_new_ssl(ctx, 0);
BIO_get_ssl(sbio, &ssl);
-
- if(!ssl) {
- fprintf(stderr, "Can't locate SSL pointer\n");
- /* whatever ... */
+ if (ssl == NULL) {
+ fprintf(stderr, "Can't locate SSL pointer\n");
+ ERR_print_errors_fp(stderr);
+ exit(1);
}
- /* Don't want any retries */
SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY);
-
- /* Create the buffering BIO */
-
bbio = BIO_new(BIO_f_buffer());
-
- /* Add to chain */
sbio = BIO_push(bbio, sbio);
+ acpt = BIO_new_accept("4433");
- acpt=BIO_new_accept("4433");
-
- /* By doing this when a new connection is established
+ /*
+ * By doing this when a new connection is established
* we automatically have sbio inserted into it. The
* BIO chain is now 'swallowed' by the accept BIO and
- * will be freed when the accept BIO is freed.
+ * will be freed when the accept BIO is freed.
*/
-
- BIO_set_accept_bios(acpt,sbio);
-
+ BIO_set_accept_bios(acpt, sbio);
out = BIO_new_fp(stdout, BIO_NOCLOSE);
/* Setup accept BIO */
- if(BIO_do_accept(acpt) <= 0) {
- fprintf(stderr, "Error setting up accept BIO\n");
- ERR_print_errors_fp(stderr);
- return 0;
+ if (BIO_do_accept(acpt) <= 0) {
+ fprintf(stderr, "Error setting up accept BIO\n");
+ ERR_print_errors_fp(stderr);
+ exit(1);
}
- /* Now wait for incoming connection */
- if(BIO_do_accept(acpt) <= 0) {
- fprintf(stderr, "Error in connection\n");
- ERR_print_errors_fp(stderr);
- return 0;
+ if (BIO_do_accept(acpt) <= 0) {
+ fprintf(stderr, "Error in connection\n");
+ ERR_print_errors_fp(stderr);
+ exit(1);
}
- /* We only want one connection so remove and free
- * accept BIO
- */
-
+ /* We only want one connection so remove and free accept BIO */
sbio = BIO_pop(acpt);
-
BIO_free_all(acpt);
- if(BIO_do_handshake(sbio) <= 0) {
- fprintf(stderr, "Error in SSL handshake\n");
- ERR_print_errors_fp(stderr);
- return 0;
+ if (BIO_do_handshake(sbio) <= 0) {
+ fprintf(stderr, "Error in SSL handshake\n");
+ ERR_print_errors_fp(stderr);
+ exit(1);
}
BIO_puts(sbio, "HTTP/1.0 200 OK\r\nContent-type: text/plain\r\n\r\n");
BIO_puts(sbio, "\r\nConnection Established\r\nRequest headers:\r\n");
BIO_puts(sbio, "--------------------------------------------------\r\n");
- for(;;) {
- len = BIO_gets(sbio, tmpbuf, 1024);
- if(len <= 0) break;
- BIO_write(sbio, tmpbuf, len);
- BIO_write(out, tmpbuf, len);
- /* Look for blank line signifying end of headers*/
- if((tmpbuf[0] == '\r') || (tmpbuf[0] == '\n')) break;
+ for ( ; ; ) {
+ len = BIO_gets(sbio, tmpbuf, 1024);
+ if (len <= 0)
+ break;
+ BIO_write(sbio, tmpbuf, len);
+ BIO_write(out, tmpbuf, len);
+ /* Look for blank line signifying end of headers*/
+ if (tmpbuf[0] == '\r' || tmpbuf[0] == '\n')
+ break;
}
BIO_puts(sbio, "--------------------------------------------------\r\n");
BIO_puts(sbio, "\r\n");
-
- /* Since there is a buffering BIO present we had better flush it */
BIO_flush(sbio);
-
BIO_free_all(sbio);
-=head1 SEE ALSO
+=head1 BUGS
+
+In OpenSSL versions before 1.0.0 the BIO_pop() call was handled incorrectly,
+the I/O BIO reference count was incorrectly incremented (instead of
+decremented) and dissociated with the SSL BIO even if the SSL BIO was not
+explicitly being popped (e.g. a pop higher up the chain). Applications which
+included workarounds for this bug (e.g. freeing BIOs more than once) should
+be modified to handle this fix or they may free up an already freed BIO.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
-TBA
+=cut
projects / openssl.git / blobdiff