generic-library/openssl
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Add documentation for SSL_has_pending()

Browse Source 
A previous commit added the SSL_has_pending() function which provides a
method for knowing whether OpenSSL has buffered, but as yet unprocessed
record data.

Reviewed-by: Tim Hudson <tjh@openssl.org>
This commit is contained in:
Matt Caswell 2016-02-16 10:36:18 +00:00
parent 8061d964e7
commit d7ded13af1
3 changed files with 43 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
doc/ssl/SSL_CTX_set_read_ahead.pod
View File

@ -37,7 +37,9 @@ ahead has been set or not.
=head1 NOTES
These functions have no impact when used with DTLS. The return values for
SSL_CTX_get_read_head() and SSL_get_read_ahead() are undefined for DTLS.
SSL_CTX_get_read_head() and SSL_get_read_ahead() are undefined for DTLS. Setting
B<read_ahead> can impact the behaviour of the SSL_pending() function
(see L<SSL_pending()>).
=head1 RETURN VALUES
@ -46,6 +48,6 @@ and non zero otherwise.
=head1 SEE ALSO
L<ssl(3)>
L<ssl(3)>, L<SSL_pending(3)>
=cut

5
doc/ssl/SSL_CTX_set_split_send_fragment.pod
View File

@ -93,7 +93,8 @@ read as much data into the read buffer as the network can provide and will fit
into the buffer. Without this set data is read into the read buffer one record
at a time. The more data that can be read, the more opportunity there is for
parallelising the processing at the cost of increased memory overhead per
connection.
connection. Setting B<read_ahead> can impact the behaviour of the SSL_pending()
function (see L<SSL_pending(3)>).
The SSL_CTX_set_default_read_buffer_len() and SSL_set_default_read_buffer_len()
functions control the size of the read buffer that will be used. The B<len>
@ -121,6 +122,6 @@ functions were added in OpenSSL 1.1.0.
=head1 SEE ALSO
L<SSL_CTX_set_read_ahead(3)>
L<SSL_CTX_set_read_ahead(3)>, L<SSL_pending(3)>
=cut

55
doc/ssl/SSL_pending.pod
View File

@ -2,41 +2,58 @@
=head1 NAME
SSL_pending - obtain number of readable bytes buffered in an SSL object
SSL_pending, SSL_has_pending - check for readable bytes buffered in an
SSL object
=head1 SYNOPSIS
#include <openssl/ssl.h>
int SSL_pending(const SSL *ssl);
int SSL_has_pending(const SSL *s);
=head1 DESCRIPTION
SSL_pending() returns the number of bytes which are available inside
B<ssl> for immediate read.
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)>.
=head1 NOTES
SSL_pending() returns the number of bytes which have been processed, buffered
and are available inside B<ssl> for immediate read.
Data are received in blocks from the peer. Therefore data can be buffered
inside B<ssl> and are ready for immediate retrieval with
L<SSL_read(3)>.
If the B<SSL> object's I<read_ahead> flag is set (see
L<SSL_CTX_set_read_ahead(3)>), additional protocol bytes (beyond the current
record) may have been read containing more TLS/SSL records. This also applies to
DTLS and pipelining (see L<SSL_CTX_set_split_send_fragment(3)>). These
additional bytes will be buffered by OpenSSL but will remain unprocessed until
they are needed. As these bytes are still in an unprocessed state SSL_pending()
will ignore them. Therefore it is possible for no more bytes to be readable from
the underlying BIO (because OpenSSL has already read them) and for SSL_pending()
to return 0, even though readable application data bytes are available (because
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 happend 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).
=head1 RETURN VALUES
The number of bytes pending is returned.
=head1 BUGS
SSL_pending() takes into account only bytes from the TLS/SSL record
that is currently being processed (if any). If the B<SSL> object's
I<read_ahead> flag is set (see
L<SSL_CTX_set_read_ahead(3)>), additional protocol
bytes may have been read containing more TLS/SSL records; these are ignored by
SSL_pending().
SSL_pending() returns the number of buffered and processed application data
bytes that are pending and are available for immediate read. SSL_has_pending()
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(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
The SSL_has_pending() function was added in OpenSSL 1.1.0.
=cut