Fix wrong information about SSL_set_connect_state()...

[openssl.git] / doc / ssl / SSL_read.pod

diff --git a/doc/ssl/SSL_read.pod b/doc/ssl/SSL_read.pod
index 91f068a1199048be905720199d1654bd99d8fa86..e9557ba1a1868b0679df6551200ddc3d9c13f950 100644 (file)
--- a/doc/ssl/SSL_read.pod
+++ b/doc/ssl/SSL_read.pod
@@ -8,7 +8,7 @@ SSL_read - read bytes from a TLS/SSL connection.
 
  #include <openssl/ssl.h>
 
 
  #include <openssl/ssl.h>
 

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

 
 =head1 DESCRIPTION
 
 
 =head1 DESCRIPTION
 


@@ -25,11 +25,25 @@ the SSL_read() operation. The behaviour of SSL_read() depends on the
 underlying BIO. 
 
 For the transparent negotiation to succeed, the B<ssl> must have been
 underlying BIO. 
 
 For the transparent negotiation to succeed, the B<ssl> must have been

-initialized to client or server mode. This is not the case if a generic
-method is being used (see L<SSL_CTX_new(3)|SSL_CTX_new(3)>, so that
+initialized to client or server mode. This is being done by calling

 L<SSL_set_connect_state(3)|SSL_set_connect_state(3)> or SSL_set_accept_state()
 L<SSL_set_connect_state(3)|SSL_set_connect_state(3)> or SSL_set_accept_state()

-must be used before the first call to an SSL_read() or
-L<SSL_write(3)|SSL_write(3)> function.
+before the first call to an SSL_read() or L<SSL_write(3)|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
+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
 
 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