| blob | 14e4853842d6eb4946782134a09a123a3c352f30 |
1 .\" $OpenBSD: SSL_read.3,v 1.4 2016/12/07 18:47:23 schwarze Exp $
2 .\" OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
3 .\"
4 .\" This file was written by Lutz Jaenicke <jaenicke@openssl.org> and
5 .\" Matt Caswell <matt@openssl.org>.
6 .\" Copyright (c) 2000, 2001, 2008, 2016 The OpenSSL Project. All rights reserved.
7 .\"
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
10 .\" are met:
11 .\"
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\"
15 .\" 2. Redistributions in binary form must reproduce the above copyright
16 .\" notice, this list of conditions and the following disclaimer in
17 .\" the documentation and/or other materials provided with the
18 .\" distribution.
19 .\"
20 .\" 3. All advertising materials mentioning features or use of this
21 .\" software must display the following acknowledgment:
22 .\" "This product includes software developed by the OpenSSL Project
23 .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
24 .\"
25 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
26 .\" endorse or promote products derived from this software without
27 .\" prior written permission. For written permission, please contact
28 .\" openssl-core@openssl.org.
29 .\"
30 .\" 5. Products derived from this software may not be called "OpenSSL"
31 .\" nor may "OpenSSL" appear in their names without prior written
32 .\" permission of the OpenSSL Project.
33 .\"
34 .\" 6. Redistributions of any form whatsoever must retain the following
35 .\" acknowledgment:
36 .\" "This product includes software developed by the OpenSSL Project
37 .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
38 .\"
39 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
40 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
41 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
42 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
43 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
44 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
45 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
46 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
47 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
48 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
49 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
50 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
51 .\"
52 .Dd $Mdocdate: December 7 2016 $
53 .Dt SSL_READ 3
54 .Os
55 .Sh NAME
56 .Nm SSL_read ,
57 .Nm SSL_peek
58 .Nd read bytes from a TLS/SSL connection
59 .Sh SYNOPSIS
60 .In openssl/ssl.h
61 .Ft int
62 .Fn SSL_read "SSL *ssl" "void *buf" "int num"
63 .Ft int
64 .Fn SSL_peek "SSL *ssl" "void *buf" "int num"
65 .Sh DESCRIPTION
66 .Fn SSL_read
67 tries to read
68 .Fa num
69 bytes from the specified
70 .Fa ssl
71 into the buffer
72 .Fa buf .
73 .Pp
74 .Fn SSL_peek
75 is identical to
76 .Fn SSL_read
77 except that no bytes are removed from the underlying BIO during
78 the read, such that a subsequent call to
79 .Fn SSL_read
80 will yield at least the same bytes once again.
81 .Pp
82 In the following,
83 .Fn SSL_read
84 and
85 .Fn SSL_peek
86 are called
87 .Dq read functions .
88 .Pp
89 If necessary, a read function will negotiate a TLS/SSL session, if
90 not already explicitly performed by
91 .Xr SSL_connect 3
92 or
93 .Xr SSL_accept 3 .
94 If the peer requests a re-negotiation, it will be performed
95 transparently during the read function operation.
96 The behaviour of the read functions depends on the underlying
97 .Vt BIO .
98 .Pp
99 For the transparent negotiation to succeed, the
100 .Fa ssl
101 must have been initialized to client or server mode.
102 This is done by calling
103 .Xr SSL_set_connect_state 3
104 or
105 .Xr SSL_set_accept_state 3
106 before the first call to a read function.
107 .Pp
108 The read functions works based on the SSL/TLS records.
109 The data are received in records (with a maximum record size of 16kB).
110 Only when a record has been completely received, it can be processed
111 (decrypted and checked for integrity).
112 Therefore data that was not retrieved at the last read call can
113 still be buffered inside the SSL layer and will be retrieved on the
114 next read call.
115 If
116 .Fa num
117 is higher than the number of bytes buffered, the read functions
118 will return with the bytes buffered.
119 If no more bytes are in the buffer, the read functions will trigger
120 the processing of the next record.
121 Only when the record has been received and processed completely
122 will the read functions return reporting success.
123 At most the contents of the record will be returned.
124 As the size of an SSL/TLS record may exceed the maximum packet size
125 of the underlying transport (e.g., TCP), it may be necessary to
126 read several packets from the transport layer before the record is
127 complete and the read call can succeed.
128 .Pp
129 If the underlying
130 .Vt BIO
131 is blocking,
132 a read function will only return once the read operation has been
133 finished or an error occurred, except when a renegotiation takes
134 place, in which case an
135 .Dv SSL_ERROR_WANT_READ
136 may occur.
137 This behavior can be controlled with the
138 .Dv SSL_MODE_AUTO_RETRY
139 flag of the
140 .Xr SSL_CTX_set_mode 3
141 call.
142 .Pp
143 If the underlying
144 .Vt BIO
145 is non-blocking, a read function will also return when the underlying
146 .Vt BIO
147 could not satisfy the needs of the function to continue the operation.
148 In this case a call to
149 .Xr SSL_get_error 3
150 with the return value of the read function will yield
151 .Dv SSL_ERROR_WANT_READ
152 or
153 .Dv SSL_ERROR_WANT_WRITE .
154 As at any time a re-negotiation is possible, a read function may
155 also cause write operations.
156 The calling process must then repeat the call after taking appropriate
157 action to satisfy the needs of the read function.
158 The action depends on the underlying
159 .Vt BIO .
160 When using a non-blocking socket, nothing is to be done, but
161 .Xr select 2
162 can be used to check for the required condition.
163 When using a buffering
164 .Vt BIO ,
165 like a
166 .Vt BIO
167 pair, data must be written into or retrieved out of the
168 .Vt BIO
169 before being able to continue.
170 .Pp
171 .Xr SSL_pending 3
172 can be used to find out whether there are buffered bytes available for
173 immediate retrieval.
174 In this case a read function can be called without blocking or
175 actually receiving new data from the underlying socket.
176 .Pp
177 When a read function operation has to be repeated because of
178 .Dv SSL_ERROR_WANT_READ
179 or
180 .Dv SSL_ERROR_WANT_WRITE ,
181 it must be repeated with the same arguments.
182 .Sh RETURN VALUES
183 The following return values can occur:
184 .Bl -tag -width Ds
185 .It >0
186 The read operation was successful.
187 The return value is the number of bytes actually read from the
188 TLS/SSL connection.
189 .It 0
190 The read operation was not successful.
191 The reason may either be a clean shutdown due to a
192 .Dq close notify
193 alert sent by the peer (in which case the
194 .Dv SSL_RECEIVED_SHUTDOWN
195 flag in the ssl shutdown state is set (see
196 .Xr SSL_shutdown 3
197 and
198 .Xr SSL_set_shutdown 3 ) .
199 It is also possible that the peer simply shut down the underlying transport and
200 the shutdown is incomplete.
201 Call
202 .Fn SSL_get_error
203 with the return value to find out whether an error occurred or the connection
204 was shut down cleanly
205 .Pq Dv SSL_ERROR_ZERO_RETURN .
206 .It <0
207 The read operation was not successful, because either an error occurred or
208 action must be taken by the calling process.
209 Call
210 .Fn SSL_get_error
211 with the return value to find out the reason.
212 .El
213 .Sh SEE ALSO
214 .Xr BIO_new 3 ,
215 .Xr ssl 3 ,
216 .Xr SSL_accept 3 ,
217 .Xr SSL_connect 3 ,
218 .Xr SSL_CTX_new 3 ,
219 .Xr SSL_CTX_set_mode 3 ,
220 .Xr SSL_get_error 3 ,
221 .Xr SSL_pending 3 ,
222 .Xr SSL_set_connect_state 3 ,
223 .Xr SSL_set_shutdown 3 ,
224 .Xr SSL_shutdown 3 ,
225 .Xr SSL_write 3