Document the newly added SSL functions

=item SSL_MODE_ENABLE_PARTIAL_WRITE

Allow SSL_write(..., n) to return r with 0 < r < n (i.e. report success

when just a single record has been written). When not set (the default),

SSL_write() will only report success once the complete chunk was written.

Once SSL_write() returns with r, r bytes have been successfully written

and the next call to SSL_write() must only send the n-r bytes left,

imitating the behaviour of write().

Allow SSL_write_ex(..., n, &r) to return with 0 < r < n (i.e. report success

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().

=item SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER

Make it possible to retry SSL_write() with changed buffer location

(the buffer contents must stay the same). This is not the default to avoid

the misconception that non-blocking SSL_write() behaves like

Make it possible to retry SSL_write_ex() or SSL_write() with changed buffer

location (the buffer contents must stay the same). This is not the default to

avoid the misconception that non-blocking SSL_write() behaves like

non-blocking write().

=item SSL_MODE_AUTO_RETRY

Never bother the application with retries if the transport is blocking.

If a renegotiation take place during normal operation, a

L<SSL_read(3)> or L<SSL_write(3)> would return

with -1 and indicate the need to retry with SSL_ERROR_WANT_READ.

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

return with a failure and indicate the need to retry with SSL_ERROR_WANT_READ.

In a non-blocking environment applications must be prepared to handle

incomplete read/write operations.

In a blocking environment, applications are not always prepared to

=head1 SEE ALSO

L<ssl(3)>, L<SSL_read(3)>, L<SSL_write(3)>, L<SSL_get_error(3)>

L<ssl(3)>, L<SSL_read_ex(3)>, L<SSL_read(3)>, L<SSL_write_ex(3)> or

L<SSL_write(3)>, L<SSL_get_error(3)>

=head1 HISTORY

writing encrypted data. SSL_CTX_set_split_send_fragment() and

SSL_set_split_send_fragment() define how data is split up into pipelines when

writing encrypted data. The number of pipelines used will be determined by the

amount of data provided to the SSL_write() call divided by

amount of data provided to the SSL_write_ex() or SSL_write() call divided by

B<split_send_fragment>.

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

then:

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

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

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

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

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

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

SSL_write called with 6001+ bytes == 4 pipelines used

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>.

SSL_get_error() returns a result code (suitable for the C "switch"

statement) for a preceding call to SSL_connect(), SSL_accept(), SSL_do_handshake(),

SSL_read(), SSL_peek(), or SSL_write() on B<ssl>.  The value returned by

that TLS/SSL I/O function must be passed to SSL_get_error() in parameter

B<ret>.

SSL_read_ex(), SSL_read(), SSL_peek_ex(), SSL_peek(), SSL_write_ex() or

SSL_write() on B<ssl>.  The value returned by that TLS/SSL I/O function must be

passed to SSL_get_error() in parameter B<ret>.

In addition to B<ssl> and B<ret>, SSL_get_error() inspects the

current thread's OpenSSL error queue.  Thus, SSL_get_error() must be

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() or SSL_peek() may want to write data and SSL_write() 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(), SSL_peek(), and SSL_write() will handle any pending handshakes.

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.

=item SSL_ERROR_WANT_CONNECT, SSL_ERROR_WANT_ACCEPT

Data is received in whole blocks known as records from the peer. A whole record

is processed (e.g. decrypted) in one go and is buffered by OpenSSL until it is

read by the application via a call to L<SSL_read(3)>.

read by the application via a call to L<SSL_read_ex(3)> or L<SSL_read(3)>.

SSL_pending() returns the number of bytes which have been processed, buffered

and are available inside B<ssl> for immediate read.

SSL_has_pending() returns 1 if B<s> has buffered data (whether processed or

unprocessed) and 0 otherwise. Note that it is possible for SSL_has_pending() to

return 1, and then a subsequent call to SSL_read() to return no data because the

unprocessed buffered data when processed yielded no application data (for

example this can happen during renegotiation). It is also possible in this

scenario for SSL_has_pending() to continue to return 1 even after an SSL_read()

call because the buffered and unprocessed data is not yet processable (e.g.

because OpenSSL has only received a partial record so far).

return 1, and then a subsequent call to SSL_read_ex() or SSL_read() to return no

data because the unprocessed buffered data when processed yielded no application

data (for example this can happen during renegotiation). It is also possible in

this scenario for SSL_has_pending() to continue to return 1 even after an

SSL_read_ex() or SSL_read() call because the buffered and unprocessed data is

not yet processable (e.g. because OpenSSL has only received a partial record so

far).

=head1 RETURN VALUES

=head1 SEE ALSO

L<SSL_read(3)>, L<SSL_CTX_set_read_ahead(3)>,

L<SSL_read_ex(3)>, L<SSL_read(3)>, L<SSL_CTX_set_read_ahead(3)>,

L<SSL_CTX_set_split_send_fragment(3)>, L<ssl(3)>

=head1 HISTORY

=head1 NAME

SSL_read - read bytes from a TLS/SSL connection

SSL_read_ex, SSL_read - read bytes from a TLS/SSL connection

=head1 SYNOPSIS

 #include <openssl/ssl.h>

 int SSL_read_ex(SSL *ssl, void *buf, size_t num, size_t *read);

 int SSL_read(SSL *ssl, void *buf, int num);

 int SSL_peek_ex(SSL *ssl, void *buf, size_t num, size_t *read);

 int SSL_peek(SSL *ssl, void *buf, int num);

=head1 DESCRIPTION

SSL_read() tries to read B<num> bytes from the specified B<ssl> into the

buffer B<buf>.

SSL_read_ex() and SSL_read() try to read B<num> bytes from the specified B<ssl>

into the buffer B<buf>. On success SSL_read_ex() will store the number of bytes

actually read in B<*read>.

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.

=head1 NOTES

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

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

also apply to SSL_peek_ex() and 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

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

the SSL_read() operation. The behaviour of SSL_read() depends on the

underlying BIO.

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

SSL_read() 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() or L<SSL_write(3)>

function.

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

L<SSL_write(3)> function.

SSL_read() works 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

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() can still be buffered inside the SSL layer and will be

retrieved on the next call to SSL_read(). If B<num> is higher than the

number of bytes buffered, 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() 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() can succeed.

If the underlying BIO is B<blocking>, 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.

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()

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

L<SSL_CTX_set_mode(3)> call.

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

when the underlying BIO could not satisfy the needs of SSL_read()

to continue the operation. In this case a call to

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() will yield B<SSL_ERROR_WANT_READ> or

return value of SSL_read_ex() or SSL_read() 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() can also cause write operations! The calling process

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

needs of 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.

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.

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

are buffered bytes available for immediate retrieval. In this case

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

data from the underlying socket.

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

new data from the underlying socket.

=head1 WARNING

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

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

with the same arguments.

=head1 RETURN VALUES

The following return values can occur:

SSL_read_ex() will return 1 for success or 0 for failure. In the event of a

failure call SSL_get_error() to find out the reason.

For SSL_read() the following return values can occur:

=over 4

=head1 SEE ALSO

L<SSL_get_error(3)>, L<SSL_write(3)>,

L<SSL_get_error(3)>, L<SSL_write_ex(3)>,

L<SSL_CTX_set_mode(3)>, L<SSL_CTX_new(3)>,

L<SSL_connect(3)>, L<SSL_accept(3)>

L<SSL_set_connect_state(3)>,