Document the newly added SSL functions

Also document SSL_peek() which was missing from the docs.
Reviewed-by: NRich Salz <rsalz@openssl.org>

doc/man3/SSL_CTX_set_mode.pod

@@ -34,26 +34,27 @@ The following mode changes are available:
 
 =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
@@ -96,7 +97,8 @@ SSL_CTX_get_mode() and SSL_get_mode() return the current bitmask.
 
 =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
 

doc/man3/SSL_CTX_set_split_send_fragment.pod

@@ -58,19 +58,19 @@ Pipelining operates slightly differently for reading encrypted data compared to
 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>.

doc/man3/SSL_get_error.pod

@@ -14,9 +14,9 @@ SSL_get_error - obtain result code for TLS/SSL I/O operation
 
 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
@@ -64,10 +64,11 @@ TLS/SSL I/O function should be retried.
 
 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
 

doc/man3/SSL_pending.pod

@@ -16,7 +16,7 @@ SSL object
 
 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.
@@ -34,12 +34,13 @@ the data is in unprocessed buffered records).
 
 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
 
@@ -49,7 +50,7 @@ returns 1 if there is buffered record data in the SSL object and 0 otherwise.
 
 =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

doc/man3/SSL_read.pod

@@ -2,82 +2,100 @@
 
 =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
 
@@ -108,7 +126,7 @@ return value B<ret> to find out the reason.
 
 =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)>,

doc/man3/SSL_set_connect_state.pod

@@ -35,8 +35,8 @@ requested, the handshake routines must be explicitly set.
 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(3)> or L<SSL_read(3)>, the
-handshake routines must be explicitly set in advance using either
+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().
 
 =head1 RETURN VALUES
@@ -47,8 +47,8 @@ information.
 =head1 SEE ALSO
 
 L<ssl(3)>, L<SSL_new(3)>, L<SSL_CTX_new(3)>,
-LL<SSL_connect(3)>, L<SSL_accept(3)>,
-L<SSL_write(3)>, L<SSL_read(3)>,
+L<SSL_connect(3)>, L<SSL_accept(3)>,
+L<SSL_write_ex(3)>, L<SSL_write(3)>, L<SSL_read_ex(3)>, L<SSL_read(3)>,
 L<SSL_do_handshake(3)>,
 L<SSL_CTX_set_ssl_version(3)>
 

doc/man3/SSL_write.pod

@@ -2,75 +2,83 @@
 
 =head1 NAME
 
-SSL_write - write bytes to a TLS/SSL connection
+SSL_write_ex, SSL_write - write bytes to a TLS/SSL connection
 
 =head1 SYNOPSIS
 
  #include <openssl/ssl.h>
 
+ int SSL_write_ex(SSL *s, const void *buf, size_t num, size_t *written);
  int SSL_write(SSL *ssl, const void *buf, int num);
 
 =head1 DESCRIPTION
 
-SSL_write() writes B<num> bytes from the buffer B<buf> into the specified
-B<ssl> connection.
+SSL_write_ex() and SSL_write() write B<num> bytes from the buffer B<buf> into
+the specified B<ssl> connection. On success SSL_write_ex() will store the number
+of bytes written in B<*written>.
 
 =head1 NOTES
 
-If necessary, SSL_write() will negotiate a TLS/SSL session, if
+If necessary, SSL_write_ex() or SSL_write() 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_write() operation. The behaviour of SSL_write() depends on the
-underlying BIO.
+the SSL_write_ex() or SSL_write() operation. The behaviour of SSL_write_ex() or
+SSL_write() 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 L<SSL_read(3)> or SSL_write() function.
+before the first call to an L<SSL_read_ex(3)>, L<SSL_read(3)>, SSL_write_ex() or
+SSL_write() function.
 
-If the underlying BIO is B<blocking>, SSL_write() will only return, once the
-write operation has been finished or an error occurred, except when a
-renegotiation take place, in which case a SSL_ERROR_WANT_READ may occur.
+If the underlying BIO is B<blocking>, SSL_write_ex() and SSL_write() will only
+return, once the write 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_write() will also return,
-when the underlying BIO could not satisfy the needs of SSL_write()
-to continue the operation. In this case a call to
+If the underlying BIO is B<non-blocking>, SSL_write_ex() or SSL_write() will
+also return, when the underlying BIO could not satisfy the needs of
+SSL_write_ex() or SSL_write() to continue the operation. In this case a call to
 L<SSL_get_error(3)> with the
-return value of SSL_write() 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_write() can also cause read operations! The calling process
-then must repeat the call after taking appropriate action to satisfy the
-needs of SSL_write(). 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.
-
-SSL_write() will only return with success, when the complete contents
-of B<buf> of length B<num> has been written. This default behaviour
+return value of SSL_write_ex() or SSL_write() 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_write_ex() or SSL_write() can also cause read operations! The
+calling process then must repeat the call after taking appropriate action to
+satisfy the needs of SSL_write_ex() or SSL_write(). 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.
+
+SSL_write_ex() or SSL_write() will only return with success, when the complete
+contents of B<buf> of length B<num> has been written. This default behaviour
 can be changed with the SSL_MODE_ENABLE_PARTIAL_WRITE option of
 L<SSL_CTX_set_mode(3)>. When this flag is set,
-SSL_write() will also return with success, when a partial write has been
-successfully completed. In this case the SSL_write() operation is considered
-completed. The bytes are sent and a new SSL_write() operation with a new
+SSL_write_ex() or SSL_write() will also return with success, when a partial
+write has been successfully completed. In this case the SSL_write_ex() or
+SSL_write() operation is considered completed. The bytes are sent and a new
+SSL_write_ex() or SSL_write() operation with a new
 buffer (with the already sent bytes removed) must be started.
 A partial write is performed with the size of a message block, which is
 16kB for SSLv3/TLSv1.
 
 =head1 WARNING
 
-When an SSL_write() operation has to be repeated because of
+When an SSL_write_ex() or SSL_write() 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.
 
-When calling SSL_write() with num=0 bytes to be sent the behaviour is
-undefined.
+When calling SSL_write_ex() or SSL_write() with num=0 bytes to be sent the
+behaviour is undefined.
 
 =head1 RETURN VALUES
 
-The following return values can occur:
+SSL_write_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_write() the following return values can occur:
 
 =over 4
 
@@ -96,7 +104,7 @@ return value B<ret> to find out the reason.
 
 =head1 SEE ALSO
 
-L<SSL_get_error(3)>, L<SSL_read(3)>,
+L<SSL_get_error(3)>, L<SSL_read_ex(3)>, L<SSL_read(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)>,

doc/man7/ssl.pod

@@ -28,8 +28,8 @@ connection with the object.
 Then the TLS/SSL handshake is performed using
 L<SSL_accept(3)> or L<SSL_connect(3)>
 respectively.
-L<SSL_read(3)> and L<SSL_write(3)> are used
-to read and write data on the TLS/SSL connection.
+L<SSL_read_ex(3)>, L<SSL_read(3)>, L<SSL_write_ex(3)> and L<SSL_write(3)> are
+used to read and write data on the TLS/SSL connection.
 L<SSL_shutdown(3)> can be used to shut down the
 TLS/SSL connection.
 
@@ -792,6 +792,7 @@ L<SSL_get_version(3)>,
 L<SSL_load_client_CA_file(3)>,
 L<SSL_new(3)>,
 L<SSL_pending(3)>,
+L<SSL_read_ex(3)>,
 L<SSL_read(3)>,
 L<SSL_rstate_string(3)>,
 L<SSL_session_reused(3)>,
@@ -803,6 +804,7 @@ L<SSL_set_shutdown(3)>,
 L<SSL_shutdown(3)>,
 L<SSL_state_string(3)>,
 L<SSL_want(3)>,
+L<SSL_write_ex(3)>,
 L<SSL_write(3)>,
 L<SSL_SESSION_free(3)>,
 L<SSL_SESSION_get_time(3)>,