SSL_READ(3ossl)

📦

version 15.1 · 2 versions

15.1 · freebsd 15.1 (latest)
14.5 · freebsd 14.5

🌸 SSL_READ — reading bytes from a TLS/SSL connection (aka the `SSL_READ(3ossl)` page) 🌸

okok so this is the OpenSSL manual page for the read girlies. SSL_read_ex, SSL_read, SSL_peek_ex, and SSL_peek — the whole bestie squad. yes they all do basically the same vibe, no they are not the same function, keep reading 💅

✨ SYNOPSIS ✨

#include <openssl/ssl.h>

int SSL_read_ex(SSL *ssl, void *buf, size_t num, size_t *readbytes);
int SSL_read(SSL *ssl, void *buf, int num);

int SSL_peek_ex(SSL *ssl, void *buf, size_t num, size_t *readbytes);
int SSL_peek(SSL *ssl, void *buf, int num);

look at them. four icons. same energy, slightly different little outfits 🎀

💖 DESCRIPTION 💖

So SSL_read_ex() and SSL_read() are gonna try to read num bytes from the specified ssl and yeet them into the buffer buf. And when it actually works? SSL_read_ex() is the organized one — it stores the number of bytes actually read into *readbytes. slay, receipts kept 💅

Now SSL_peek_ex() and SSL_peek() are identical to SSL_read_ex() and SSL_read() respectively, except — and this is the whole thing — no bytes are actually removed from the underlying BIO during the read. so it's giving "look but don't touch" 🫶 which means a subsequent call to SSL_read_ex() or SSL_read() will yield at least the same bytes. at least!! no cap ✨

🦋 NOTES 🦋

In the paragraphs below, a "read function" is defined as one of SSL_read_ex(), SSL_read(), SSL_peek_ex() or SSL_peek(). so whenever you see "a read function," just know it means any one of the four besties 💜

If necessary, a read function will negotiate a TLS/SSL session — if that wasn't already explicitly performed by SSL_connect(3) or SSL_accept(3). and if the peer requests a re-negotiation? it gets performed transparently during the read function operation. sneaky but polite. the behaviour of the read functions depends on the underlying BIO, fyi — it's giving "I'm flexible, I adapt" 💁‍♀️

For the transparent negotiation to succeed, the ssl must have been initialized to client or server mode. that happens by calling SSL_set_connect_state(3) or SSL_set_accept_state() before the first invocation of a read function. pregame before the function, periodt 🔥

🎀 the record tea (this part is important, bestie)

The read functions work based on the SSL/TLS records. the data are received in records (with a maximum record size of 16kB). and here's the thing — only when a record has been completely received can it be processed (decryption and check of integrity). so it's all-or-nothing per record, iykyk 😭

So because of that:

data that was not retrieved at the last read call can still be buffered inside the SSL layer, and will be retrieved on the next read call 🫶
if num is higher than the number of bytes buffered, then the read functions will return with the bytes buffered
if no more bytes are in the buffer, the read functions will trigger the processing of the next record
only when the record has been received and processed completely will the read functions return reporting success 📈
at most the contents of one record will be returned
and since 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 the read call can succeed. so like, chill, it's assembling itself 🧚

🌈 SSL_MODE_AUTO_RETRY shenanigans

If SSL_MODE_AUTO_RETRY has been switched off and a non-application data record has been processed, the read function can return and set the error to SSL_ERROR_WANT_READ. in that case there might still be unprocessed data available in the BIO. and if read ahead was set using SSL_CTX_set_read_ahead(3), there might also still be unprocessed data available in the SSL. all this behaviour can be controlled using the SSL_CTX_set_mode(3) call 🔧

💀 blocking BIO vs nonblocking BIO

blocked vs nonblocked is literally the main character conflict of this page

If the underlying BIO is blocking: a read function will only return once the read operation has been finished or an error occurred — except when a non-application data record has been processed and SSL_MODE_AUTO_RETRY is not set. and note: if SSL_MODE_AUTO_RETRY is set and only non-application data is available, the call will hang. yes. hang. like it's just gonna sit there 😭💀

If the underlying BIO is nonblocking: a read function will also return when the underlying BIO could not satisfy the needs of the function to continue the operation. in that case, a call to SSL_get_error(3) with the return value of the read function will yield SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE. and because at any time it's possible that non-application data needs to be sent, a read function can also cause write operations. plot twist, I know 😳

The calling process then must repeat the call after taking appropriate action to satisfy the needs of the read function. and that action depends on the underlying BIO:

when using a nonblocking 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

⭐ the shortcut

SSL_pending(3) can be used to find out whether there are buffered bytes available for immediate retrieval. in this case the read function can be called without blocking or actually receiving new data from the underlying socket. free real estate, honestly 👑

🦄 QUIC moment

When used with a QUIC SSL object, calling an I/O function such as SSL_read() allows internal network event processing to be performed. and it is important that this processing is performed regularly. so if an application is not using thread assisted mode, an application should ensure that an I/O function such as SSL_read() is called regularly, or alternatively ensure that SSL_handle_events() is called regularly. see openssl-quic(7) and SSL_handle_events(3) for more information 🙈

👑 RETURN VALUES 👑

So SSL_read_ex() and SSL_peek_ex() will return 1 for success or 0 for failure.

success means that 1 or more application data bytes have been read from the SSL connection ✅
failure means that no bytes could be read from the SSL connection ❌

and failures can be retryable (e.g. we are waiting for more bytes to be delivered by the network) or non-retryable (e.g. a fatal network error). in the event of a failure, call SSL_get_error(3) to find out the reason, which indicates whether the call is retryable or not. don't guess, just ask the function 💅

For SSL_read() and SSL_peek() the following return values can occur:

> 0 — The read operation was successful. the return value is the number of bytes actually read from the TLS/SSL connection 🌸
<= 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 SSL_get_error(3) with the return value ret to find out the reason.

⚠️ ok important lore drop: 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. the old docs are not invited to the group chat anymore 🙅‍♀️

(yes, the whole extended friend group. go say hi 🫶)

🦋 HISTORY 🦋

The SSL_read_ex() and SSL_peek_ex() functions were added in OpenSSL 1.1.1. so they're the newer little siblings and we love them ✨

💜 COPYRIGHT 💜

Licensed under the Apache License 2.0 (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 <https://www.openssl.org/source/license.html>.

aaaand that's the page, bestie 🎀 go read some bytes, don't let your records hang, and always call SSL_get_error(3) before you spiral 💅✨

version 3.5.6 · dated 2026-04-07 · laterrrr 🦋

📦 where this page comes from

freebsd 15.1: base 15.1
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms