SSL_write(3) — Subroutines

NAME

SSL_write − Write bytes to a TLS/SSL connection.

SYNOPSIS

#include <openssl/ssl.h>
int SSL_write(
        SSL ∗ssl,
        const void ∗buf,
        int num );

DESCRIPTION

The SSL_write() function writes num bytes from the buffer buf into the specified ssl connection.

NOTES

If necessary, the SSL_write() function will negotiate a TLS/SSL session, if not already explicitly performed by SSL_connect() or SSL_accept(). If the peer requests a renegotiation, it will be performed transparently during the SSL_write() operation. The behavior of SSL_write() depends on the underlying BIO.

For the transparent negotiation to succeed, the ssl must have been initialized to client or server mode. This is done by calling the SSL_set_connect_state() or SSL_set_accept_state() functions before the first call to an SSL_read() or SSL_write() function.

If the underlying BIO is blocking, SSL_write() will only return once the write operation finishes or an error occurs, except when a renegotiation take place, in which case an SSL_ERROR_WANT_READ might occur. This behavior can be controlled with the SSL_MODE_AUTO_RETRY flag of the SSL_CTX_set_mode() function.

If the underlying BIO is non-blocking, SSL_write() will also return, when the underlying BIO could not satisfy the needs of SSL_write() to continue the operation. In this case a call to SSL_get_error() with the return value of SSL_write() will yield SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE. As at any time a renegotiation is possible, a call to SSL_write() can also cause read operations. The calling process then must repeat the call after taking appropriate action to satisfy the needs of SSL_write(). 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.

The SSL_write() function will only return with success when the complete contents of buf of length num has been written. This default behavior can be changed with the SSL_MODE_ENABLE_PARTIAL_WRITE option of SSL_CTX_set_mode(). When this flag is set, SSL_write() will also return with success when a partial write successfully completes. In this case, the SSL_write() operation is considered complete. The bytes are sent and a new SSL_write() operation with a new buffer (with the previously sent bytes removed) must be started. A partial write is performed with the size of a message block, which is 16kB for SSLv3/TLSv1.

RESTRICTIONS

When an SSL_write() operation has to be repeated because of SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE, it must be repeated with the same arguments.

WARNINGS

When calling SSL_write() with num= 0 bytes the behavior is undefined.

RETURN VALUES

The following return values can occur:

>0The write operation was successful, the return value is the number of bytes actually written to the TLS/SSL connection.

0The write operation was not successful. The underlying connection was probably closed. Call SSL_get_error() with the return value ret to determine if an error occurred or the connection was shut down cleanly (SSL_ERROR_ZERO_RETURN). SSLv2 (deprecated) does not support a shutdown alert protocol, so it can only be detected if an underlying connection was closed. It cannot check why the closure happened.

<0The write operation was not successful, because either an error occurred or action must be taken by the calling process. Call SSL_get_error() with the return value ret to find the reason.

Museum

Related Articles