• NAME
• SYNOPSIS
• DESCRIPTION
• NOTES
• RETURN VALUES
• SEE ALSO
• HISTORY
• COPYRIGHT

NAME

SSL_read_ex, SSL_read, SSL_peek_ex, SSL_peek - read bytes from a TLS/SSL connection

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);

DESCRIPTION

SSL_read_ex() and SSL_read() try to read num bytes from the specified ssl into the buffer buf. On success SSL_read_ex() will store the number of bytes actually read in *readbytes.

SSL_peek_ex() and SSL_peek() are identical to SSL_read_ex() and SSL_read() respectively except no bytes are actually removed from the underlying BIO during the read, so that a subsequent call to SSL_read_ex() or SSL_read() will yield at least the same bytes.

NOTES

In the paragraphs below a "read function" is defined as one of SSL_read_ex(), SSL_read(), SSL_peek_ex() or SSL_peek().

If necessary, a read function will negotiate a TLS/SSL session, if not already explicitly performed by SSL_accept(3). If the peer requests a re-negotiation, it will be performed transparently during the read function operation. The behaviour of the read functions depends on the underlying BIO.

For the transparent negotiation to succeed, the ssl must have been initialized to client or server mode. This is being done by calling SSL_CTX_set_read_ahead(3), there might also still be unprocessed data available in the SSL. This behaviour can be controlled using the SSL_get_error(3) with the return value of the read function will yield SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE. As at any time it's possible that non-application data needs to be sent, a read function can also cause write operations. The calling process then must repeat the call after taking appropriate action to satisfy the needs of the read function. The action depends on the underlying BIO. When using a non-blocking 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.

RETURN VALUES

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. 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 > 0