X-Git-Url: https://git.openssl.org/?p=openssl.git;a=blobdiff_plain;f=doc%2Fcrypto%2FBIO_f_ssl.pod;h=a56ee2b92f2bae32ee0b498df4da6d03e29021d9;hp=ba36eff80e4f5bc90e02cc0e2426247acf43d507;hb=2c281ebb6c651566c11cfdfefd09379c62784f37;hpb=37b08e836541a48c253ce3ba0af4e6eb8a7972d5

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