From 7714dc5ea1174ca50cd12e5013683284f66c2dd3 Mon Sep 17 00:00:00 2001 From: Matt Caswell Date: Thu, 20 Oct 2016 15:04:21 +0100 Subject: [PATCH] Document the newly added SSL functions Also document SSL_peek() which was missing from the docs. Reviewed-by: Rich Salz --- doc/man3/SSL_CTX_set_mode.pod | 26 +++--- doc/man3/SSL_CTX_set_split_send_fragment.pod | 10 +- doc/man3/SSL_get_error.pod | 15 +-- doc/man3/SSL_pending.pod | 17 ++-- doc/man3/SSL_read.pod | 98 ++++++++++++-------- doc/man3/SSL_set_connect_state.pod | 8 +- doc/man3/SSL_write.pod | 72 +++++++------- doc/man7/ssl.pod | 6 +- 8 files changed, 142 insertions(+), 110 deletions(-) diff --git a/doc/man3/SSL_CTX_set_mode.pod b/doc/man3/SSL_CTX_set_mode.pod index 1b3e783ad6..270a71301c 100644 --- a/doc/man3/SSL_CTX_set_mode.pod +++ b/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 or L would return -with -1 and indicate the need to retry with SSL_ERROR_WANT_READ. +L, L, L or L 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, L, L, L +L, L, L, L or +L, L =head1 HISTORY diff --git a/doc/man3/SSL_CTX_set_split_send_fragment.pod b/doc/man3/SSL_CTX_set_split_send_fragment.pod index accf5af247..b34fefd6f0 100644 --- a/doc/man3/SSL_CTX_set_split_send_fragment.pod +++ b/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. For example if B is set to 2000 and B 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 must always be less than or equal to B. By default it is set to be equal to B. diff --git a/doc/man3/SSL_get_error.pod b/doc/man3/SSL_get_error.pod index ddd72f7065..d165b888b5 100644 --- a/doc/man3/SSL_get_error.pod +++ b/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. The value returned by -that TLS/SSL I/O function must be passed to SSL_get_error() in parameter -B. +SSL_read_ex(), SSL_read(), SSL_peek_ex(), SSL_peek(), SSL_write_ex() or +SSL_write() on B. The value returned by that TLS/SSL I/O function must be +passed to SSL_get_error() in parameter B. In addition to B and B, 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 and B. 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 diff --git a/doc/man3/SSL_pending.pod b/doc/man3/SSL_pending.pod index f6ed5652a1..642cd4b434 100644 --- a/doc/man3/SSL_pending.pod +++ b/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. +read by the application via a call to L or L. SSL_pending() returns the number of bytes which have been processed, buffered and are available inside B for immediate read. @@ -34,12 +34,13 @@ the data is in unprocessed buffered records). SSL_has_pending() returns 1 if B 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, L, +L, L, L, L, L =head1 HISTORY diff --git a/doc/man3/SSL_read.pod b/doc/man3/SSL_read.pod index 8dff2448d0..fa3583e552 100644 --- a/doc/man3/SSL_read.pod +++ b/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 + 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 bytes from the specified B into the -buffer B. +SSL_read_ex() and SSL_read() try to read B bytes from the specified B +into the buffer B. 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 or L. 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 must have been initialized to client or server mode. This is being done by calling L or SSL_set_accept_state() -before the first call to an SSL_read() or L -function. +before the first call to an SSL_read_ex(), SSL_read(), L or +L 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 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, 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 +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, 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 call. -If the underlying BIO is B, 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, 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 with the -return value of SSL_read() will yield B or +return value of SSL_read_ex() or SSL_read() will yield B or B. 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 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 or B, 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 to find out the reason. =head1 SEE ALSO -L, L, +L, L, L, L, L, L L, diff --git a/doc/man3/SSL_set_connect_state.pod b/doc/man3/SSL_set_connect_state.pod index 60c18a4510..1fe7040a02 100644 --- a/doc/man3/SSL_set_connect_state.pod +++ b/doc/man3/SSL_set_connect_state.pod @@ -35,8 +35,8 @@ requested, the handshake routines must be explicitly set. When using the L or L routines, the correct handshake routines are automatically set. When performing a transparent negotiation -using L or L, the -handshake routines must be explicitly set in advance using either +using L, L L or L, +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, L, L, -LL, L, -L, L, +L, L, +L, L, L, L, L, L diff --git a/doc/man3/SSL_write.pod b/doc/man3/SSL_write.pod index 5ab079042e..45b34a4ff7 100644 --- a/doc/man3/SSL_write.pod +++ b/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 + 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 bytes from the buffer B into the specified -B connection. +SSL_write_ex() and SSL_write() write B bytes from the buffer B into +the specified B 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 or L. 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 must have been initialized to client or server mode. This is being done by calling L or SSL_set_accept_state() -before the first call to an L or SSL_write() function. +before the first call to an L, L, SSL_write_ex() or +SSL_write() function. -If the underlying BIO is B, 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, 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 call. -If the underlying BIO is B, 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, 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 with the -return value of SSL_write() will yield B or -B. 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 of length B has been written. This default behaviour +return value of SSL_write_ex() or SSL_write() will yield B +or B. 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 of length B has been written. This default behaviour can be changed with the SSL_MODE_ENABLE_PARTIAL_WRITE option of L. 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 or B, 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 to find out the reason. =head1 SEE ALSO -L, L, +L, L, L L, L, L, L L, diff --git a/doc/man7/ssl.pod b/doc/man7/ssl.pod index ce163f4df0..7b5b39e938 100644 --- a/doc/man7/ssl.pod +++ b/doc/man7/ssl.pod @@ -28,8 +28,8 @@ connection with the object. Then the TLS/SSL handshake is performed using L or L respectively. -L and L are used -to read and write data on the TLS/SSL connection. +L, L, L and L are +used to read and write data on the TLS/SSL connection. L can be used to shut down the TLS/SSL connection. @@ -792,6 +792,7 @@ L, L, L, L, +L, L, L, L, @@ -803,6 +804,7 @@ L, L, L, L, +L, L, L, L, -- 2.25.1