1SSL_READ(3ossl) OpenSSL SSL_READ(3ossl)
2
6 SSL_read_ex, SSL_read, SSL_peek_ex, SSL_peek - read bytes from a
7 TLS/SSL connection
8
10 #include <openssl/ssl.h>
11 int SSL_read_ex(SSL *ssl, void *buf, size_t num, size_t *readbytes);
13 int SSL_read(SSL *ssl, void *buf, int num);
14 int SSL_peek_ex(SSL *ssl, void *buf, size_t num, size_t *readbytes);
16 int SSL_peek(SSL *ssl, void *buf, int num);
17
19 SSL_read_ex() and SSL_read() try to read num bytes from the specified
20 ssl into the buffer buf. On success SSL_read_ex() will store the number
21 of bytes actually read in *readbytes.
22 SSL_peek_ex() and SSL_peek() are identical to SSL_read_ex() and
24 SSL_read() respectively except no bytes are actually removed from the
25 underlying BIO during the read, so that a subsequent call to
26 SSL_read_ex() or SSL_read() will yield at least the same bytes.
27
29 In the paragraphs below a "read function" is defined as one of
30 SSL_read_ex(), SSL_read(), SSL_peek_ex() or SSL_peek().
31 If necessary, a read function will negotiate a TLS/SSL session, if not
33 already explicitly performed by SSL_connect(3) or SSL_accept(3). If the
34 peer requests a re-negotiation, it will be performed transparently
35 during the read function operation. The behaviour of the read functions
36 depends on the underlying BIO.
37 For the transparent negotiation to succeed, the ssl must have been
39 initialized to client or server mode. This is being done by calling
40 SSL_set_connect_state(3) or SSL_set_accept_state() before the first
41 invocation of a read function.
42 The read functions work based on the SSL/TLS records. The data are
44 received in records (with a maximum record size of 16kB). Only when a
45 record has been completely received, can it be processed (decryption
46 and check of integrity). Therefore, data that was not retrieved at the
47 last read call can still be buffered inside the SSL layer and will be
48 retrieved on the next read call. If num is higher than the number of
49 bytes buffered then the read functions will return with the bytes
50 buffered. If no more bytes are in the buffer, the read functions will
51 trigger the processing of the next record. Only when the record has
52 been received and processed completely will the read functions return
53 reporting success. At most the contents of one record will be returned.
54 As the size of an SSL/TLS record may exceed the maximum packet size of
55 the underlying transport (e.g. TCP), it may be necessary to read
56 several packets from the transport layer before the record is complete
57 and the read call can succeed.
58 If SSL_MODE_AUTO_RETRY has been switched off and a non-application data
60 record has been processed, the read function can return and set the
61 error to SSL_ERROR_WANT_READ. In this case there might still be
62 unprocessed data available in the BIO. If read ahead was set using
63 SSL_CTX_set_read_ahead(3), there might also still be unprocessed data
64 available in the SSL. This behaviour can be controlled using the
65 SSL_CTX_set_mode(3) call.
66 If the underlying BIO is blocking, a read function will only return
68 once the read operation has been finished or an error occurred, except
69 when a non-application data record has been processed and
70 SSL_MODE_AUTO_RETRY is not set. Note that if SSL_MODE_AUTO_RETRY is
71 set and only non-application data is available the call will hang.
72 If the underlying BIO is nonblocking, a read function will also return
74 when the underlying BIO could not satisfy the needs of the function to
75 continue the operation. In this case a call to SSL_get_error(3) with
76 the return value of the read function will yield SSL_ERROR_WANT_READ or
77 SSL_ERROR_WANT_WRITE. As at any time it's possible that non-
78 application data needs to be sent, a read function can also cause write
79 operations. The calling process then must repeat the call after taking
80 appropriate action to satisfy the needs of the read function. The
81 action depends on the underlying BIO. When using a nonblocking socket,
82 nothing is to be done, but select() can be used to check for the
83 required condition. When using a buffering BIO, like a BIO pair, data
84 must be written into or retrieved out of the BIO before being able to
85 continue.
86 SSL_pending(3) can be used to find out whether there are buffered bytes
88 available for immediate retrieval. In this case the read function can
89 be called without blocking or actually receiving new data from the
90 underlying socket.
91
93 SSL_read_ex() and SSL_peek_ex() will return 1 for success or 0 for
94 failure. Success means that 1 or more application data bytes have been
95 read from the SSL connection. Failure means that no bytes could be
96 read from the SSL connection. Failures can be retryable (e.g. we are
97 waiting for more bytes to be delivered by the network) or non-retryable
98 (e.g. a fatal network error). In the event of a failure call
99 SSL_get_error(3) to find out the reason which indicates whether the
100 call is retryable or not.
101 For SSL_read() and SSL_peek() the following return values can occur:
103 > 0 The read operation was successful. The return value is the number
105 of bytes actually read from the TLS/SSL connection.
106 <= 0
108 The read operation was not successful, because either the
109 connection was closed, an error occurred or action must be taken by
110 the calling process. Call SSL_get_error(3) with the return value
111 ret to find out the reason.
112 Old documentation indicated a difference between 0 and -1, and that
114 -1 was retryable. You should instead call SSL_get_error() to find
115 out if it's retryable.
116
118 SSL_get_error(3), SSL_write_ex(3), SSL_CTX_set_mode(3), SSL_CTX_new(3),
119 SSL_connect(3), SSL_accept(3) SSL_set_connect_state(3), SSL_pending(3),
120 SSL_shutdown(3), SSL_set_shutdown(3), ssl(7), bio(7)
121
123 The SSL_read_ex() and SSL_peek_ex() functions were added in OpenSSL
124 1.1.1.
125
127 Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.
128 Licensed under the Apache License 2.0 (the "License"). You may not use
130 this file except in compliance with the License. You can obtain a copy
131 in the file LICENSE in the source distribution or at
132 <https://www.openssl.org/source/license.html>.
1333.1.1 2023-08-31 SSL_READ(3ossl)