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