1 .\" $NetBSD: SSL_read.3,v 1.14 2015/06/12 17:01:14 christos Exp $
3 .\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
6 .\" ========================================================================
7 .de Sp \" Vertical space (when we can't use .PP)
11 .de Vb \" Begin verbatim text
16 .de Ve \" End verbatim text
20 .\" Set up some character translations and predefined strings. \*(-- will
21 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
22 .\" double quote, and \*(R" will give a right double quote. \*(C+ will
23 .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
24 .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
25 .\" nothing in troff, for use with C<>.
27 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
31 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
32 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
47 .\" Escape single quotes in literal strings from groff's Unicode transform.
51 .\" If the F register is turned on, we'll generate index entries on stderr for
52 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
53 .\" entries marked with X<> in POD. Of course, you'll have to process the
54 .\" output yourself in some meaningful fashion.
56 .\" Avoid warning from groff about undefined register 'F'.
60 .if \n(.g .if rF .nr rF 1
61 .if (\n(rF:(\n(.g==0)) \{
64 . tm Index:\\$1\t\\n%\t"\\$2"
74 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
75 .\" Fear. Run. Save yourself. No user-serviceable parts.
76 . \" fudge factors for nroff and troff
85 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
91 . \" simple accents for nroff and troff
101 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
102 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
103 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
104 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
105 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
106 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
108 . \" troff and (daisy-wheel) nroff accents
109 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
110 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
111 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
112 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
113 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
114 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
115 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
116 .ds ae a\h'-(\w'a'u*4/10)'e
117 .ds Ae A\h'-(\w'A'u*4/10)'E
118 . \" corrections for vroff
119 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
120 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
121 . \" for low resolution devices (crt and lpr)
122 .if \n(.H>23 .if \n(.V>19 \
135 .\" ========================================================================
137 .IX Title "SSL_read 3"
138 .TH SSL_read 3 "2014-06-05" "1.0.1n" "OpenSSL"
139 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
140 .\" way too many mistakes in technical documents.
144 SSL_read \- read bytes from a TLS/SSL connection.
148 .IX Header "SYNOPSIS"
150 \& #include <openssl/ssl.h>
152 \& int SSL_read(SSL *ssl, void *buf, int num);
155 .IX Header "DESCRIPTION"
156 \&\fISSL_read()\fR tries to read \fBnum\fR bytes from the specified \fBssl\fR into the
160 If necessary, \fISSL_read()\fR will negotiate a \s-1TLS/SSL\s0 session, if
161 not already explicitly performed by \fISSL_connect\fR\|(3) or
162 \&\fISSL_accept\fR\|(3). If the
163 peer requests a re-negotiation, it will be performed transparently during
164 the \fISSL_read()\fR operation. The behaviour of \fISSL_read()\fR depends on the
165 underlying \s-1BIO. \s0
167 For the transparent negotiation to succeed, the \fBssl\fR must have been
168 initialized to client or server mode. This is being done by calling
169 \&\fISSL_set_connect_state\fR\|(3) or \fISSL_set_accept_state()\fR
170 before the first call to an \fISSL_read()\fR or \fISSL_write\fR\|(3)
173 \&\fISSL_read()\fR works based on the \s-1SSL/TLS\s0 records. The data are received in
174 records (with a maximum record size of 16kB for SSLv3/TLSv1). Only when a
175 record has been completely received, it can be processed (decryption and
176 check of integrity). Therefore data that was not retrieved at the last
177 call of \fISSL_read()\fR can still be buffered inside the \s-1SSL\s0 layer and will be
178 retrieved on the next call to \fISSL_read()\fR. If \fBnum\fR is higher than the
179 number of bytes buffered, \fISSL_read()\fR will return with the bytes buffered.
180 If no more bytes are in the buffer, \fISSL_read()\fR will trigger the processing
181 of the next record. Only when the record has been received and processed
182 completely, \fISSL_read()\fR will return reporting success. At most the contents
183 of the record will be returned. As the size of an \s-1SSL/TLS\s0 record may exceed
184 the maximum packet size of the underlying transport (e.g. \s-1TCP\s0), it may
185 be necessary to read several packets from the transport layer before the
186 record is complete and \fISSL_read()\fR can succeed.
188 If the underlying \s-1BIO\s0 is \fBblocking\fR, \fISSL_read()\fR will only return, once the
189 read operation has been finished or an error occurred, except when a
190 renegotiation take place, in which case a \s-1SSL_ERROR_WANT_READ\s0 may occur.
191 This behaviour can be controlled with the \s-1SSL_MODE_AUTO_RETRY\s0 flag of the
192 \&\fISSL_CTX_set_mode\fR\|(3) call.
194 If the underlying \s-1BIO\s0 is \fBnon-blocking\fR, \fISSL_read()\fR will also return
195 when the underlying \s-1BIO\s0 could not satisfy the needs of \fISSL_read()\fR
196 to continue the operation. In this case a call to
197 \&\fISSL_get_error\fR\|(3) with the
198 return value of \fISSL_read()\fR will yield \fB\s-1SSL_ERROR_WANT_READ\s0\fR or
199 \&\fB\s-1SSL_ERROR_WANT_WRITE\s0\fR. As at any time a re-negotiation is possible, a
200 call to \fISSL_read()\fR can also cause write operations! The calling process
201 then must repeat the call after taking appropriate action to satisfy the
202 needs of \fISSL_read()\fR. The action depends on the underlying \s-1BIO.\s0 When using a
203 non-blocking socket, nothing is to be done, but \fIselect()\fR can be used to check
204 for the required condition. When using a buffering \s-1BIO,\s0 like a \s-1BIO\s0 pair, data
205 must be written into or retrieved out of the \s-1BIO\s0 before being able to continue.
207 \&\fISSL_pending\fR\|(3) can be used to find out whether there
208 are buffered bytes available for immediate retrieval. In this case
209 \&\fISSL_read()\fR can be called without blocking or actually receiving new
210 data from the underlying socket.
213 When an \fISSL_read()\fR operation has to be repeated because of
214 \&\fB\s-1SSL_ERROR_WANT_READ\s0\fR or \fB\s-1SSL_ERROR_WANT_WRITE\s0\fR, it must be repeated
215 with the same arguments.
217 .IX Header "RETURN VALUES"
218 The following return values can occur:
221 The read operation was successful; the return value is the number of
222 bytes actually read from the \s-1TLS/SSL\s0 connection.
224 The read operation was not successful. The reason may either be a clean
225 shutdown due to a \*(L"close notify\*(R" alert sent by the peer (in which case
226 the \s-1SSL_RECEIVED_SHUTDOWN\s0 flag in the ssl shutdown state is set
227 (see \fISSL_shutdown\fR\|(3),
228 \&\fISSL_set_shutdown\fR\|(3)). It is also possible, that
229 the peer simply shut down the underlying transport and the shutdown is
230 incomplete. Call \fISSL_get_error()\fR with the return value \fBret\fR to find out,
231 whether an error occurred or the connection was shut down cleanly
232 (\s-1SSL_ERROR_ZERO_RETURN\s0).
234 SSLv2 (deprecated) does not support a shutdown alert protocol, so it can
235 only be detected, whether the underlying connection was closed. It cannot
236 be checked, whether the closure was initiated by the peer or by something
240 The read operation was not successful, because either an error occurred
241 or action must be taken by the calling process. Call \fISSL_get_error()\fR with the
242 return value \fBret\fR to find out the reason.
244 .IX Header "SEE ALSO"
245 \&\fISSL_get_error\fR\|(3), \fISSL_write\fR\|(3),
246 \&\fISSL_CTX_set_mode\fR\|(3), \fISSL_CTX_new\fR\|(3),
247 \&\fISSL_connect\fR\|(3), \fISSL_accept\fR\|(3)
248 \&\fISSL_set_connect_state\fR\|(3),
249 \&\fISSL_pending\fR\|(3),
250 \&\fISSL_shutdown\fR\|(3), \fISSL_set_shutdown\fR\|(3),
251 \&\fIssl\fR\|(3), \fIopenssl_bio\fR\|(3)