BIO_f_ssl() docs.

doc/crypto/BIO_ctrl.pod

@@ -91,6 +91,15 @@ case of a file BIO some data may be available in the FILE structures
 internal buffers but it is not possible to determine this in a
 portably way. For other types of BIO they may not be supported.
 
+Filter BIOs if the do not internally handle a particular BIO_ctrl()
+operation usually pass the operation to the next BIO in the chain.
+This often means there is no need to locate the required BIO for
+a particular operation, it can be called on a chain and it will
+be automatically passed to the relevant BIO.
+
+Source/sink BIOs will return an error if the do not recognise the
+BIO_ctrl() operation.
+
 =head1 SEE ALSO
 
 TBA

doc/crypto/BIO_f_ssl.pod

@@ -0,0 +1,175 @@
+=pod
+
+=head1 NAME
+
+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
+
+=head1 SYNOPSIS
+
+ #include <openssl/bio.h>
+ #include <openssl/ssl.h>
+
+ 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);
+
+ 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);
+ void BIO_ssl_shutdown(BIO *bio);
+
+=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. 
+
+I/O performed on an SSL BIO communicates using the SSL protocol with
+the SSLs read and write BIOs.
+
+If a BIO is appended to an SSL BIO using BIO_push() it is automatically
+used as the SSL BIOs read and write BIOs.
+
+Calling BIO_reset() on an SSL BIO closes down any current SSL connection
+by calling SSL_shutdown(). BIO_reset() is then sent to the next BIO in
+the chain: this will typically disconnect the underlying transport.
+The SSL BIO is then reset to the initial accept or connect state.
+
+If the close flag is set when an SSL BIO is freed then the internal
+SSL structure is also freed using SSL_free().
+
+BIO_set_ssl() sets the internal SSL pointer of BIO B<b> to B<ssl> using
+the close flag B<c>.
+
+BIO_get_ssl() retrieves the SSL pointer of BIO B<b>, it can then be
+manipulated using the standard SSL library functions.
+
+BIO_set_ssl_mode() sets the SSL BIO mode to B<client>. If B<client>
+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) 
+the SSL session is automatically renegotiated. B<num> must be at
+least 512 bytes.
+
+BIO_set_ssl_renegotiate_timeout() sets the renegotiate timeout to
+B<seconds>. When the renegotiate timeout elapses the sesssion is
+automatically renegotiated.
+
+BIO_get_num_renegotiates() returns the total number of session
+renegotiations due to I/O or timeout.
+
+BIO_new_ssl() allocates an SSL BIO using SSL_CTX B<ctx> and using
+client mode if B<client> is non zero.
+
+BIO_new_ssl_connect() creates a new BIO chain consisting of an
+SSL BIO (using B<ctx>) followed by a connect BIO.
+
+BIO_new_buffer_ssl_connect() creates a new BIO chain consisting
+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 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.
+
+BIO_ssl_shutdown() closes down an SSL connection on BIO
+chain B<bio>. It does this by locating the SSL BIO in the
+chain and calling SSL_shutdown() on its internal SSL
+pointer.
+
+=head1 NOTES
+
+SSL BIOs are exceptional in that if the underlying transport
+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.
+
+In OpenSSL 0.9.6 and later 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.
+
+Since unknown BIO_ctrl() operations are sent through filter
+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.
+
+=head1 RETURN VALUES
+
+TBA
+
+=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)>.
+
+ BIO *sbio, *out;
+ int len;
+ char tmpbuf[1024];
+ SSL_CTX *ctx;
+ SSL *ssl;
+
+ ERR_load_crypto_strings();
+ ERR_load_SSL_strings();
+ OpenSSL_add_all_algorithms();
+
+ ctx = SSL_CTX_new(SSLv23_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.
+  */
+
+ sbio = BIO_new_ssl_connect(ctx);
+
+ 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);
+
+ /* We might want to do other things with ssl here */
+
+ BIO_set_conn_hostname(sbio, "localhost: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 ... */
+	}
+
+ /* 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);
+ }
+ BIO_free_all(sbio);
+ BIO_free(out);
+
+=head1 SEE ALSO
+
+TBA

doc/crypto/BIO_read.pod

@@ -52,7 +52,7 @@ I/O structure and may block as a result. Instead select() (or equivalent)
 should be combined with non blocking I/O so successive reads will request
 a retry instead of blocking.
 
-See the L<BIO_should_retry(3)|BIO_should_retry(3)> for details of how to
+See L<BIO_should_retry(3)|BIO_should_retry(3)> for details of how to
 determine the cause of a retry and other I/O issues.
 
 If the BIO_gets() function is not supported by a BIO then it possible to
@@ -60,6 +60,7 @@ work around this by adding a buffering BIO L<BIO_f_buffer(3)|BIO_f_buffer(3)>
 to the chain.
 
 =head1 SEE ALSO
+
 L<BIO_should_retry(3)|BIO_should_retry(3)>
 
 TBA