1 files changed, 295 insertions, 0 deletions

diff --git a/src/lib/libcrypto/man/BIO_s_bio.3 b/src/lib/libcrypto/man/BIO_s_bio.3
new file mode 100644
index 0000000000..af7bdabd33
--- /dev/null
+++ b/src/lib/libcrypto/man/BIO_s_bio.3
@@ -0,0 +1,295 @@
+.Dd $Mdocdate: February 16 2015 $
+.Dt BIO_S_BIO 3
+.Os
+.Sh NAME
+.Nm BIO_s_bio ,
+.Nm BIO_make_bio_pair ,
+.Nm BIO_destroy_bio_pair ,
+.Nm BIO_shutdown_wr ,
+.Nm BIO_set_write_buf_size ,
+.Nm BIO_get_write_buf_size ,
+.Nm BIO_new_bio_pair ,
+.Nm BIO_get_write_guarantee ,
+.Nm BIO_ctrl_get_write_guarantee ,
+.Nm BIO_get_read_request ,
+.Nm BIO_ctrl_get_read_request ,
+.Nm BIO_ctrl_reset_read_request
+.Nd BIO pair BIO
+.Sh SYNOPSIS
+.In openssl/bio.h
+.Ft BIO_METHOD *
+.Fo BIO_s_bio
+.Fa void
+.Fc
+.Bd -unfilled
+#define BIO_make_bio_pair(b1, b2) \e
+        (int)BIO_ctrl(b1, BIO_C_MAKE_BIO_PAIR, 0, b2)
+#define BIO_destroy_bio_pair(b) \e
+        (int)BIO_ctrl(b, BIO_C_DESTROY_BIO_PAIR, 0, NULL)
+#define BIO_shutdown_wr(b) \e
+        (int)BIO_ctrl(b, BIO_C_SHUTDOWN_WR, 0, NULL)
+#define BIO_set_write_buf_size(b, size) \e
+        (int)BIO_ctrl(b, BIO_C_SET_WRITE_BUF_SIZE, size, NULL)
+#define BIO_get_write_buf_size(b, size) \e
+        (size_t)BIO_ctrl(b, BIO_C_GET_WRITE_BUF_SIZE, size, NULL)
+.Ed
+.Pp
+.Ft int
+.Fo BIO_new_bio_pair
+.Fa "BIO **bio1"
+.Fa "size_t writebuf1"
+.Fa "BIO **bio2"
+.Fa "size_t writebuf2"
+.Fc
+.Bd -unfilled
+#define BIO_get_write_guarantee(b) \e
+        (int)BIO_ctrl(b, BIO_C_GET_WRITE_GUARANTEE, 0, NULL)
+.Ed
+.Pp
+.Ft size_t
+.Fo BIO_ctrl_get_write_guarantee
+.Fa "BIO *b"
+.Fc
+.Bd -unfilled
+#define BIO_get_read_request(b) \e
+        (int)BIO_ctrl(b, BIO_C_GET_READ_REQUEST, 0, NULL)
+.Ed
+.Pp
+.Ft size_t
+.Fo BIO_ctrl_get_read_request
+.Fa "BIO *b"
+.Fc
+.Ft int
+.Fo BIO_ctrl_reset_read_request
+.Fa "BIO *b"
+.Fc
+.Sh DESCRIPTION
+.Fn BIO_s_bio
+returns the method for a BIO pair.
+A BIO pair is a pair of source/sink BIOs where data written to either
+half of the pair is buffered and can be read from the other half.
+Both halves must usually be handled by the same application thread
+since no locking is done on the internal data structures.
+.Pp
+Since BIO chains typically end in a source/sink BIO,
+it is possible to make this one half of a BIO pair and
+have all the data processed by the chain under application control.
+.Pp
+One typical use of BIO pairs is
+to place TLS/SSL I/O under application control.
+This can be used when the application wishes to use a non standard
+transport for TLS/SSL or the normal socket routines are inappropriate.
+.Pp
+Calls to
+.Xr BIO_read 3
+will read data from the buffer or request a retry if no data is available.
+.Pp
+Calls to
+.Xr BIO_write 3
+will place data in the buffer or request a retry if the buffer is full.
+.Pp
+The standard calls
+.Xr BIO_ctrl_pending 3
+and
+.Xr BIO_ctrl_wpending 3
+can be used to determine the amount of pending data
+in the read or write buffer.
+.Pp
+.Xr BIO_reset 3
+clears any data in the write buffer.
+.Pp
+.Fn BIO_make_bio_pair
+joins two separate BIOs into a connected pair.
+.Pp
+.Fn BIO_destroy_pair
+destroys the association between two connected BIOs.
+Freeing up any half of the pair will automatically destroy the association.
+.Pp
+.Fn BIO_shutdown_wr
+is used to close down a BIO
+.Fa b .
+After this call no further writes on BIO
+.Fa 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.
+.Pp
+.Fn BIO_set_write_buf_size
+sets the write buffer size of BIO
+.Fa b
+to
+.Fa size .
+If the size is not initialized a default value is used.
+This is currently 17K, sufficient for a maximum size TLS record.
+.Pp
+.Fn BIO_get_write_buf_size
+returns the size of the write buffer.
+.Pp
+.Fn BIO_new_bio_pair
+combines the calls to
+.Xr BIO_new 3 ,
+.Fn BIO_make_bio_pair
+and
+.Fn BIO_set_write_buf_size
+to create a connected pair of BIOs
+.Fa bio1
+and
+.Fa bio2
+with write buffer sizes
+.Fa writebuf1
+and
+.Fa writebuf2 .
+If either size is zero, then the default size is used.
+.Fn BIO_new_bio_pair
+does not check whether
+.Fa bio1
+or
+.Fa bio2
+do point to some other BIO, the values are overwritten,
+.Xr BIO_free 3
+is not called.
+.Pp
+.Fn BIO_get_write_guarantee
+and
+.Fn BIO_ctrl_get_write_guarantee
+return the maximum length of data
+that can be currently written to the BIO.
+Writes larger than this value will return a value from
+.Xr BIO_write 3
+less than the amount requested or if the buffer is full request a retry.
+.Fn BIO_ctrl_get_write_guarantee
+is a function whereas
+.Fn BIO_get_write_guarantee
+is a macro.
+.Pp
+.Fn BIO_get_read_request
+and
+.Fn BIO_ctrl_get_read_request
+return the amount of data requested, or the buffer size if it is less,
+if the last read attempt at the other half of the BIO pair failed
+due to an empty buffer.
+This can be used to determine how much data should be
+written to the BIO so the next read will succeed:
+this is most useful in TLS/SSL applications where the amount of
+data read is usually meaningful rather than just a buffer size.
+After a successful read this call will return zero.
+It also will return zero once new data has been written
+satisfying the read request or part of it.
+Note that
+.Fn BIO_get_read_request
+never returns an amount larger than that returned by
+.Fn BIO_get_write_guarantee .
+.Pp
+.Fn BIO_ctrl_reset_read_request
+can also be used to reset the value returned by
+.Fn BIO_get_read_request
+to zero.
+.Sh RETURN VALUES
+.Fn BIO_new_bio_pair
+returns 1 on success, with the new BIOs available in
+.Fa bio1
+and
+.Fa bio2 ,
+or 0 on failure, with NULL pointers stored into the locations for
+.Fa bio1
+and
+.Fa bio2 .
+Check the error stack for more information.
+.\" XXX More return values need to be added here.
+.Sh NOTES
+Both halves of a BIO pair should be freed.
+Even if one half is implicitly freed due to a
+.Xr BIO_free_all 3
+or
+.Xr SSL_free 3
+call, the other half still needs to be freed.
+.Pp
+When used in bidirectional applications (such as TLS/SSL)
+care should be taken to flush any data in the write buffer.
+This can be done by calling
+.Xr BIO_pending 3
+on the other half of the pair and, if any data is pending,
+reading it and sending it to the underlying transport.
+This must be done before any normal processing (such as calling
+.Xr select 2 )
+due to a request and
+.Xr BIO_should_read 3
+being true.
+.Pp
+To see why this is important,
+consider a case where a request is sent using
+.Xr BIO_write 3
+and a response read with
+.Xr BIO_read 3 ,
+this can occur during an TLS/SSL handshake for example.
+.Xr BIO_write 3
+will succeed and place data in the write buffer.
+.Xr BIO_read 3
+will initially fail and
+.Xr BIO_should_read 3
+will be true.
+If the application then waits for data to become available
+on the underlying transport before flushing the write buffer,
+it will never succeed because the request was never sent.
+.Sh EXAMPLE
+The BIO pair can be used to have full control
+over the network access of an application.
+The application can call
+.Xr select 2
+on the socket as required without having to go through the SSL-interface.
+.Bd -literal -offset 2n
+BIO *internal_bio, *network_bio;
+\&...
+BIO_new_bio_pair(internal_bio, 0, network_bio, 0);
+SSL_set_bio(ssl, internal_bio, internal_bio);
+SSL_operations();
+\&...
+
+application |   TLS-engine
+   |        |
+   +----------> SSL_operations()
+            |     /\e    ||
+            |     ||    \e/
+            |   BIO-pair (internal_bio)
+   +----------< BIO-pair (network_bio)
+   |        |
+ socket     |
+
+\&...
+SSL_free(ssl);          /* implicitly frees internal_bio */
+BIO_free(network_bio);
+\&...
+.Ed
+.Pp
+As the BIO pair will only buffer the data and never directly access
+the connection, it behaves non-blocking and will return as soon as
+the write buffer is full or the read buffer is drained.
+Then the application has to flush the write buffer
+and/or fill the read buffer.
+.Pp
+Use
+.Xr BIO_ctrl_pending 3
+to find out whether data is buffered in the BIO
+and must be transfered to the network.
+Use
+.Fn BIO_ctrl_get_read_request
+to find out how many bytes must be written into the buffer before the
+.Xr SSL_operation 3
+can successfully be continued.
+.Sh SEE ALSO
+.Xr bio 3 ,
+.Xr BIO_read 3 ,
+.Xr BIO_should_retry 3 ,
+.Xr ssl 3 ,
+.Xr SSL_set_bio 3
+.Sh CAVEATS
+As the data is buffered,
+.Xr SSL_operation 3
+may return with an
+.Dv ERROR_SSL_WANT_READ
+condition, but there is still data in the write buffer.
+An application must not rely on the error value of
+.Xr SSL_operation 3
+but must assure that the write buffer is always flushed first.
+Otherwise a deadlock may occur as the peer might be waiting
+for the data before being able to continue.