1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
|
=pod
=head1 NAME
SSL_read - read bytes from a TLS/SSL connection
=head1 SYNOPSIS
#include <openssl/ssl.h>
int SSL_read(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>.
=head1 NOTES
If necessary, 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.
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.
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
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
L<SSL_get_error(3)> with the
return value of 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.
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.
=head1 WARNING
When an 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:
=over 4
=item E<gt> 0
The read operation was successful.
The return value is the number of bytes actually read from the TLS/SSL
connection.
=item Z<><= 0
The read operation was not successful, because either the connection was closed,
an error occurred or action must be taken by the calling process.
Call L<SSL_get_error(3)> with the return value B<ret> to find out the reason.
Old documentation indicated a difference between 0 and -1, and that -1 was
retryable.
You should instead call SSL_get_error() to find out if it's retryable.
=back
=head1 SEE ALSO
L<SSL_get_error(3)>, L<SSL_write(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)>,
L<SSL_pending(3)>,
L<SSL_shutdown(3)>, L<SSL_set_shutdown(3)>,
L<ssl(3)>, L<bio(3)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut
|
