Updates various man pages based on review feedback received.

when just a single record has been written). This works in a similar way for

SSL_write(). When not set (the default), SSL_write_ex() or SSL_write() will only

report success once the complete chunk was written. Once SSL_write_ex() or

SSL_write() returns successful, r bytes have been written and the next call to

SSL_write_ex() or SSL_write() must only send the n-r bytes left, imitating the

behaviour of write().

SSL_write() returns successful, B<r> bytes have been written and the next call

to SSL_write_ex() or SSL_write() must only send the n-r bytes left, imitating

the behaviour of write().

=item SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER

For example if B<split_send_fragment> is set to 2000 and B<max_pipelines> is 4

then:

SSL_write(_ex) called with 0-2000 bytes == 1 pipeline used

SSL_write/SSL_write_ex called with 0-2000 bytes == 1 pipeline used

SSL_write(_ex) called with 2001-4000 bytes == 2 pipelines used

SSL_write/SSL_write_ex called with 2001-4000 bytes == 2 pipelines used

SSL_write(_ex) called with 4001-6000 bytes == 3 pipelines used

SSL_write/SSL_write_ex called with 4001-6000 bytes == 3 pipelines used

SSL_write(_ex) called with 6001+ bytes == 4 pipelines used

SSL_write/SSL_write_ex called with 6001+ bytes == 4 pipelines used

B<split_send_fragment> must always be less than or equal to

B<max_send_fragment>. By default it is set to be equal to B<max_send_fragment>.

Caveat: Any TLS/SSL I/O function can lead to either of

B<SSL_ERROR_WANT_READ> and B<SSL_ERROR_WANT_WRITE>.  In particular,

SSL_read_ex(), SSL_read() SSL_peek_ex() or SSL_peek() may want to write data and

SSL_write() or SSL_write_ex() may want to read data.  This is mainly because

SSL_read_ex(), SSL_read(), SSL_peek_ex(), or SSL_peek() may want to write data

and SSL_write() or SSL_write_ex() may want to read data.  This is mainly because

TLS/SSL handshakes may occur at any time during the protocol (initiated by

either the client or the server); SSL_read_ex(), SSL_read(), SSL_peek_ex(),

SSL_peek(), SSL_write_ex() and SSL_write() will handle any pending handshakes.

SSL_peek(), SSL_write_ex(), and SSL_write() will handle any pending handshakes.

=item SSL_ERROR_WANT_CONNECT, SSL_ERROR_WANT_ACCEPT

SSL_peek_ex() and SSL_peek() are identical to SSL_read_ex() and SSL_read()

respectively except no bytes are actually removed from the underlying BIO during

the read, so that a subsequent call to SSL_read_ex() or SSL_read() will yield

the same bytes.

at least the same bytes.

=head1 NOTES

In this notes section all comments that apply to SSL_read_ex() or SSL_read()

also apply to SSL_peek_ex() and SSL_peek().

In the paragraphs below a "read function" is defined as one of SSL_read_ex(),

SSL_read(), SSL_peek_ex() or SSL_peek().

If necessary, SSL_read_ex() or SSL_read() will negotiate a TLS/SSL session, if

not already explicitly performed by L<SSL_connect(3)> or

L<SSL_accept(3)>. If the

If necessary, a read function will negotiate a TLS/SSL session, if not already

explicitly performed by L<SSL_connect(3)> or L<SSL_accept(3)>. If the

peer requests a re-negotiation, it will be performed transparently during

the SSL_read_ex() or SSL_read() operation. The behaviour of SSL_read_ex() and

SSL_read() depends on the underlying BIO.

the read function operation. The behaviour of the read functions depends on the

underlying BIO.

For the transparent negotiation to succeed, the B<ssl> must have been

initialized to client or server mode. This is being done by calling

L<SSL_set_connect_state(3)> or SSL_set_accept_state()

before the first call to an SSL_read_ex(), SSL_read(), L<SSL_write_ex(3)> or

L<SSL_write(3)> function.

SSL_read_ex() and SSL_read() work based on the SSL/TLS records. The data are

received in records (with a maximum record size of 16kB for SSLv3/TLSv1). Only

when a record has been completely received, it can be processed (decryption and

check of integrity). Therefore data that was not retrieved at the last

call of SSL_read_ex() or SSL_read() can still be buffered inside the SSL layer

and will be retrieved on the next call to SSL_read_ex() or SSL_read(). If B<num>

is higher than the number of bytes buffered, SSL_read_ex() or SSL_read() will

return with the bytes buffered. If no more bytes are in the buffer, SSL_read()

will trigger the processing of the next record. Only when the record has been

received and processed completely, SSL_read_ex() or SSL_read() will return

reporting success. At most the contents of the record will be returned. As the

size of an SSL/TLS record may exceed the maximum packet size of the underlying

transport (e.g. TCP), it may be necessary to read several packets from the

transport layer before the record is complete and SSL_read_ex() or SSL_read()

L<SSL_set_connect_state(3)> or SSL_set_accept_state() before the first

invocation of a read function.

The read functions work based on the SSL/TLS records. The data are received in

records (with a maximum record size of 16kB). Only when a record has been

completely received, can it be processed (decryption and check of integrity).

Therefore data that was not retrieved at the last read call can still be

buffered inside the SSL layer and will be retrieved on the next read

call. If B<num> is higher than the number of bytes buffered then the read

functions will return with the bytes buffered. If no more bytes are in the

buffer, the read functions will trigger the processing of the next record.

Only when the record has been received and processed completely will the read

functions return reporting success. At most the contents of the record will

be returned. As the size of an SSL/TLS record may exceed the maximum packet size

of the underlying transport (e.g. TCP), it may be necessary to read several

packets from the transport layer before the record is complete and the read call

can succeed.

If the underlying BIO is B<blocking>, SSL_read_ex() or SSL_read() will only

return, once the read operation has been finished or an error occurred, except

when a renegotiation take place, in which case a SSL_ERROR_WANT_READ may occur.

This behaviour can be controlled with the SSL_MODE_AUTO_RETRY flag of the

If the underlying BIO is B<blocking>, a read function will only return once the

read operation has been finished or an error occurred, except when a

renegotiation takes place, in which case a SSL_ERROR_WANT_READ may occur. This

behaviour can be controlled with the SSL_MODE_AUTO_RETRY flag of the

L<SSL_CTX_set_mode(3)> call.

If the underlying BIO is B<non-blocking>, SSL_read_ex() or SSL_read() will also

return when the underlying BIO could not satisfy the needs of SSL_read_ex() or

SSL_read() to continue the operation. In this case a call to

L<SSL_get_error(3)> with the

return value of SSL_read_ex() or SSL_read() will yield B<SSL_ERROR_WANT_READ> or

If the underlying BIO is B<non-blocking>, a read function will also return when

the underlying BIO could not satisfy the needs of the function to continue the

operation. In this case a call to L<SSL_get_error(3)> with the

return value of the read function will yield B<SSL_ERROR_WANT_READ> or

B<SSL_ERROR_WANT_WRITE>. As at any time a re-negotiation is possible, a

call to SSL_read_ex() or SSL_read() can also cause write operations! The calling

process then must repeat the call after taking appropriate action to satisfy the

needs of SSL_read_ex() or SSL_read(). The action depends on the underlying BIO.

When using a non-blocking socket, nothing is to be done, but select() can be

used to check for the required condition. When using a buffering BIO, like a

BIO pair, data must be written into or retrieved out of the BIO before being

able to continue.

a read function can also cause write operations! The calling process then must

repeat the call after taking appropriate action to satisfy the needs of the read

function. The action depends on the underlying BIO. When using a non-blocking

socket, nothing is to be done, but select() can be used to check for the

required condition. When using a buffering BIO, like a BIO pair, data must be

written into or retrieved out of the BIO before being able to continue.

L<SSL_pending(3)> can be used to find out whether there

are buffered bytes available for immediate retrieval. In this case

SSL_read_ex() or SSL_read() can be called without blocking or actually receiving

the read function can be called without blocking or actually receiving

new data from the underlying socket.

=head1 WARNING

When an SSL_read_ex() or SSL_read() operation has to be repeated because of

B<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE>, it must be repeated

When a read function operation has to be repeated because L<SSL_get_error(3)>

returned B<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE>, it must be repeated

with the same arguments.

=head1 RETURN VALUES

When using the L<SSL_connect(3)> or

L<SSL_accept(3)> routines, the correct handshake

routines are automatically set. When performing a transparent negotiation

using L<SSL_write_ex(3)>, L<SSL_write(3)> L<SSL_read_ex(3)> or L<SSL_read(3)>,

using L<SSL_write_ex(3)>, L<SSL_write(3)>, L<SSL_read_ex(3)>, or L<SSL_read(3)>,

the handshake routines must be explicitly set in advance using either

SSL_set_connect_state() or SSL_set_accept_state().