diff options
author | Dr. Stephen Henson <steve@openssl.org> | 2000-09-16 21:21:01 +0000 |
---|---|---|
committer | Dr. Stephen Henson <steve@openssl.org> | 2000-09-16 21:21:01 +0000 |
commit | 2c281ebb6c651566c11cfdfefd09379c62784f37 (patch) | |
tree | 2acb6156379052629d979686ff0d24420249b15e /doc | |
parent | 37b08e836541a48c253ce3ba0af4e6eb8a7972d5 (diff) | |
download | openssl-2c281ebb6c651566c11cfdfefd09379c62784f37.tar.gz |
New macro BIO_set_shutdown_wr().
Update docs.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/crypto/BIO_f_ssl.pod | 142 | ||||
-rw-r--r-- | doc/crypto/BIO_s_accept.pod | 4 | ||||
-rw-r--r-- | doc/crypto/BIO_s_bio.pod | 15 |
3 files changed, 154 insertions, 7 deletions
diff --git a/doc/crypto/BIO_f_ssl.pod b/doc/crypto/BIO_f_ssl.pod index ba36eff80e..a56ee2b92f 100644 --- a/doc/crypto/BIO_f_ssl.pod +++ b/doc/crypto/BIO_f_ssl.pod @@ -30,6 +30,8 @@ BIO_ssl_shutdown - SSL BIO 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) + =head1 DESCRIPTION BIO_f_ssl() returns the SSL BIO method. This is a filter BIO which @@ -37,7 +39,8 @@ is a wrapper round the OpenSSL SSL routines adding a BIO "flavour" to SSL I/O. I/O performed on an SSL BIO communicates using the SSL protocol with -the SSLs read and write BIOs. +the SSLs read and write BIOs. If an SSL connection is not established +then an attempt is made to establish one on the first I/O call. If a BIO is appended to an SSL BIO using BIO_push() it is automatically used as the SSL BIOs read and write BIOs. @@ -91,6 +94,14 @@ chain B<bio>. It does this by locating the SSL BIO in the chain and calling SSL_shutdown() on its internal SSL pointer. +BIO_do_handshake() attempts to complete an SSL handshake on the +supplied BIO and establish the SSL connection. It returns 1 +if the connection was established successfully. A zero or negative +value is returned if the connection could not be established, the +call BIO_should_retry() should be used for non blocking connect BIOs +to determine if the call should be retried. If an SSL connection has +already been established this call has no effect. + =head1 NOTES SSL BIOs are exceptional in that if the underlying transport @@ -109,6 +120,10 @@ BIOs the servers name and port can be set using BIO_set_host() on the BIO returned by BIO_new_ssl_connect() without having to locate the connect BIO first. +Applications do not have to call BIO_do_handshake() but may wish +to do so to separate the handshake process from other I/O +processing. + =head1 RETURN VALUES TBA @@ -129,6 +144,10 @@ unencrypted example in L<BIO_s_connect(3)|BIO_s_connect(3)>. ERR_load_SSL_strings(); OpenSSL_add_all_algorithms(); + /* We would seed the PRNG here if the platform didn't + * do it automatically + */ + ctx = SSL_CTX_new(SSLv23_client_method()); /* We'd normally set some stuff like the verify paths and @@ -157,7 +176,13 @@ unencrypted example in L<BIO_s_connect(3)|BIO_s_connect(3)>. fprintf(stderr, "Error connecting to server\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); + /* whatever ... */ + } /* Could examine ssl here to get connection info */ @@ -170,6 +195,119 @@ unencrypted example in L<BIO_s_connect(3)|BIO_s_connect(3)>. BIO_free_all(sbio); BIO_free(out); +Here is a simple server example. It makes use of a buffering +BIO to allow lines to be read from the SSL BIO using BIO_gets. +It creates a pseudo web page containing the actual request from +a client and also echoes the request to standard output. + + BIO *sbio, *bbio, *acpt, *out; + int len; + char tmpbuf[1024]; + SSL_CTX *ctx; + SSL *ssl; + + ERR_load_crypto_strings(); + ERR_load_SSL_strings(); + OpenSSL_add_all_algorithms(); + + /* 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; + } + + /* Might do other things here like setting verify locations and + * DH and/or RSA temporary key callbacks + */ + + /* New SSL BIO setup as server */ + sbio=BIO_new_ssl(ctx,0); + + BIO_get_ssl(sbio, &ssl); + + if(!ssl) { + fprintf(stderr, "Can't locate SSL pointer\n"); + /* whatever ... */ + } + + /* 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"); + + /* 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. + */ + + 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; + } + + /* Now wait for incoming connection */ + if(BIO_do_accept(acpt) <= 0) { + fprintf(stderr, "Error in connection\n"); + ERR_print_errors_fp(stderr); + return 0; + } + + /* 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; + } + + BIO_puts(sbio, "HTTP/1.0 200 OK\r\nContent-type: text/html\r\n\r\n"); + BIO_puts(sbio, "<pre>\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; + } + + BIO_puts(sbio, "--------------------------------------------------\r\n"); + BIO_puts(sbio, "</pre>\r\n"); + + /* Since there is a buffering BIO present we had better flush it */ + BIO_flush(sbio); + + BIO_free_all(sbio); + =head1 SEE ALSO TBA diff --git a/doc/crypto/BIO_s_accept.pod b/doc/crypto/BIO_s_accept.pod index ddb1f9a2b0..c49da7fb02 100644 --- a/doc/crypto/BIO_s_accept.pod +++ b/doc/crypto/BIO_s_accept.pod @@ -75,7 +75,9 @@ BIO_set_nbio_accept() sets the accept socket to blocking mode BIO_set_accept_bios() can be used to set a chain of BIOs which will be duplicated and prepended to the chain when an incoming connection is received. This is useful if, for example, a -buffering BIO is required for each connection. +buffering or SSL BIO is required for each connection. The +chain of BIOs must not be freed after this call, they will +be automatically freed when the accept BIO is freed. BIO_set_bind_mode() and BIO_get_bind_mode() set and retrieve the current bind mode. If BIO_BIND_NORMAL (the default) is set diff --git a/doc/crypto/BIO_s_bio.pod b/doc/crypto/BIO_s_bio.pod index d3e3989a14..cf357c669d 100644 --- a/doc/crypto/BIO_s_bio.pod +++ b/doc/crypto/BIO_s_bio.pod @@ -2,10 +2,10 @@ =head1 NAME -BIO_s_bio, BIO_make_bio_pair, BIO_destroy_bio_pair, BIO_set_write_buf_size, -BIO_get_write_buf_size, BIO_new_bio_pair, BIO_get_write_guarantee, -BIO_ctrl_get_write_guarantee, BIO_get_read_request, BIO_ctrl_get_read_request, -BIO_ctrl_reset_read_request - BIO pair BIO +BIO_s_bio, BIO_make_bio_pair, BIO_destroy_bio_pair, BIO_set_shutdown_wr, +BIO_set_write_buf_size, BIO_get_write_buf_size, BIO_new_bio_pair, +BIO_get_write_guarantee, BIO_ctrl_get_write_guarantee, BIO_get_read_request, +BIO_ctrl_get_read_request, BIO_ctrl_reset_read_request - BIO pair BIO =head1 SYNOPSIS @@ -16,6 +16,8 @@ BIO_ctrl_reset_read_request - BIO pair BIO #define BIO_make_bio_pair(b1,b2) (int)BIO_ctrl(b1,BIO_C_MAKE_BIO_PAIR,0,b2) #define BIO_destroy_bio_pair(b) (int)BIO_ctrl(b,BIO_C_DESTROY_BIO_PAIR,0,NULL) + #define BIO_set_shutdown_wr(b) (int)BIO_ctrl(b, BIO_C_SHUTDOWN_WR, 0, NULL) + #define BIO_set_write_buf_size(b,size) (int)BIO_ctrl(b,BIO_C_SET_WRITE_BUF_SIZE,size,NULL) #define BIO_get_write_buf_size(b,size) (size_t)BIO_ctrl(b,BIO_C_GET_WRITE_BUF_SIZE,size,NULL) @@ -60,6 +62,11 @@ BIO_make_bio_pair() joins two separate BIOs into a connected pair. BIO_destroy_pair() destroys the association between two connected BIOs. Freeing up any half of the pair will automatically destroy the association. +BIO_set_shutdown_wr() is used to close down a BIO B<b>. After this call no further +writes on BIO B<b> are allowed (they will return an error). Reads on the other +half of the pair will return any pending data or EOF when all pending data has +been read. + BIO_set_write_buf_size() sets the write buffer size of BIO B<b> to B<size>. If the size is not initialized a default value is used. This is currently 17K, sufficient for a maximum size TLS record. |