doc/man3/SSL_read.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 SSL_read_ex, SSL_read - read bytes from a TLS/SSL connection
   6
   7 =head1 SYNOPSIS
   8
   9  #include <openssl/ssl.h>
  10
  11  int SSL_read_ex(SSL *ssl, void *buf, size_t num, size_t *read);
  12  int SSL_read(SSL *ssl, void *buf, int num);
  13
  14  int SSL_peek_ex(SSL *ssl, void *buf, size_t num, size_t *read);
  15  int SSL_peek(SSL *ssl, void *buf, int num);
  16
  17 =head1 DESCRIPTION
  18
  19 SSL_read_ex() and SSL_read() try to read B<num> bytes from the specified B<ssl>
  20 into the buffer B<buf>. On success SSL_read_ex() will store the number of bytes
  21 actually read in B<*read>.
  22
  23 SSL_peek_ex() and SSL_peek() are identical to SSL_read_ex() and SSL_read()
  24 respectively except no bytes are actually removed from the underlying BIO during
  25 the read, so that a subsequent call to SSL_read_ex() or SSL_read() will yield
  26 the same bytes.
  27
  28 =head1 NOTES
  29
  30 In this notes section all comments that apply to SSL_read_ex() or SSL_read()
  31 also apply to SSL_peek_ex() and SSL_peek().
  32
  33 If necessary, SSL_read_ex() or SSL_read() will negotiate a TLS/SSL session, if
  34 not already explicitly performed by L<SSL_connect(3)> or
  35 L<SSL_accept(3)>. If the
  36 peer requests a re-negotiation, it will be performed transparently during
  37 the SSL_read_ex() or SSL_read() operation. The behaviour of SSL_read_ex() and
  38 SSL_read() depends on the underlying BIO.
  39
  40 For the transparent negotiation to succeed, the B<ssl> must have been
  41 initialized to client or server mode. This is being done by calling
  42 L<SSL_set_connect_state(3)> or SSL_set_accept_state()
  43 before the first call to an SSL_read_ex(), SSL_read(), L<SSL_write_ex(3)> or
  44 L<SSL_write(3)> function.
  45
  46 SSL_read_ex() and SSL_read() work based on the SSL/TLS records. The data are
  47 received in records (with a maximum record size of 16kB for SSLv3/TLSv1). Only
  48 when a record has been completely received, it can be processed (decryption and
  49 check of integrity). Therefore data that was not retrieved at the last
  50 call of SSL_read_ex() or SSL_read() can still be buffered inside the SSL layer
  51 and will be retrieved on the next call to SSL_read_ex() or SSL_read(). If B<num>
  52 is higher than the number of bytes buffered, SSL_read_ex() or SSL_read() will
  53 return with the bytes buffered. If no more bytes are in the buffer, SSL_read()
  54 will trigger the processing of the next record. Only when the record has been
  55 received and processed completely, SSL_read_ex() or SSL_read() will return
  56 reporting success. At most the contents of the record will be returned. As the
  57 size of an SSL/TLS record may exceed the maximum packet size of the underlying
  58 transport (e.g. TCP), it may be necessary to read several packets from the
  59 transport layer before the record is complete and SSL_read_ex() or SSL_read()
  60 can succeed.
  61
  62 If the underlying BIO is B<blocking>, SSL_read_ex() or SSL_read() will only
  63 return, once the read operation has been finished or an error occurred, except
  64 when a renegotiation take place, in which case a SSL_ERROR_WANT_READ may occur.
  65 This behaviour can be controlled with the SSL_MODE_AUTO_RETRY flag of the
  66 L<SSL_CTX_set_mode(3)> call.
  67
  68 If the underlying BIO is B<non-blocking>, SSL_read_ex() or SSL_read() will also
  69 return when the underlying BIO could not satisfy the needs of SSL_read_ex() or
  70 SSL_read() to continue the operation. In this case a call to
  71 L<SSL_get_error(3)> with the
  72 return value of SSL_read_ex() or SSL_read() will yield B<SSL_ERROR_WANT_READ> or
  73 B<SSL_ERROR_WANT_WRITE>. As at any time a re-negotiation is possible, a
  74 call to SSL_read_ex() or SSL_read() can also cause write operations! The calling
  75 process then must repeat the call after taking appropriate action to satisfy the
  76 needs of SSL_read_ex() or SSL_read(). The action depends on the underlying BIO.
  77 When using a non-blocking socket, nothing is to be done, but select() can be
  78 used to check for the required condition. When using a buffering BIO, like a
  79 BIO pair, data must be written into or retrieved out of the BIO before being
  80 able to continue.
  81
  82 L<SSL_pending(3)> can be used to find out whether there
  83 are buffered bytes available for immediate retrieval. In this case
  84 SSL_read_ex() or SSL_read() can be called without blocking or actually receiving
  85 new data from the underlying socket.
  86
  87 =head1 WARNING
  88
  89 When an SSL_read_ex() or SSL_read() operation has to be repeated because of
  90 B<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE>, it must be repeated
  91 with the same arguments.
  92
  93 =head1 RETURN VALUES
  94
  95 SSL_read_ex() will return 1 for success or 0 for failure. In the event of a
  96 failure call SSL_get_error() to find out the reason.
  97
  98 For SSL_read() the following return values can occur:
  99
 100 =over 4
 101
 102 =item E<gt>0
 103
 104 The read operation was successful; the return value is the number of
 105 bytes actually read from the TLS/SSL connection.
 106
 107 =item Z<>0
 108
 109 The read operation was not successful. The reason may either be a clean
 110 shutdown due to a "close notify" alert sent by the peer (in which case
 111 the SSL_RECEIVED_SHUTDOWN flag in the ssl shutdown state is set
 112 (see L<SSL_shutdown(3)>,
 113 L<SSL_set_shutdown(3)>). It is also possible, that
 114 the peer simply shut down the underlying transport and the shutdown is
 115 incomplete. Call SSL_get_error() with the return value B<ret> to find out,
 116 whether an error occurred or the connection was shut down cleanly
 117 (SSL_ERROR_ZERO_RETURN).
 118
 119 =item E<lt>0
 120
 121 The read operation was not successful, because either an error occurred
 122 or action must be taken by the calling process. Call SSL_get_error() with the
 123 return value B<ret> to find out the reason.
 124
 125 =back
 126
 127 =head1 SEE ALSO
 128
 129 L<SSL_get_error(3)>, L<SSL_write_ex(3)>,
 130 L<SSL_CTX_set_mode(3)>, L<SSL_CTX_new(3)>,
 131 L<SSL_connect(3)>, L<SSL_accept(3)>
 132 L<SSL_set_connect_state(3)>,
 133 L<SSL_pending(3)>,
 134 L<SSL_shutdown(3)>, L<SSL_set_shutdown(3)>,
 135 L<ssl(3)>, L<bio(3)>
 136
 137 =head1 COPYRIGHT
 138
 139 Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
 140
 141 Licensed under the OpenSSL license (the "License").  You may not use
 142 this file except in compliance with the License.  You can obtain a copy
 143 in the file LICENSE in the source distribution or at
 144 L<https://www.openssl.org/source/license.html>.
 145
 146 =cut