.\"
.\"	$OpenBSD: SSL_write.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $
.\"
.Dd $Mdocdate: November 5 2016 $
.Dt SSL_WRITE 3
.Os
.Sh NAME
.Nm SSL_write
.Nd write bytes to a TLS/SSL connection
.Sh SYNOPSIS
.In openssl/ssl.h
.Ft int
.Fn SSL_write "SSL *ssl" "const void *buf" "int num"
.Sh DESCRIPTION
.Fn SSL_write
writes
.Fa num
bytes from the buffer
.Fa buf
into the specified
.Fa ssl
connection.
.Sh NOTES
If necessary,
.Fn SSL_write
will negotiate a TLS/SSL session, if not already explicitly performed by
.Xr SSL_connect 3
or
.Xr SSL_accept 3 .
If the peer requests a re-negotiation,
it will be performed transparently during the
.Fn SSL_write
operation.
The behaviour of
.Fn SSL_write
depends on the underlying
.Vt BIO .
.Pp
For the transparent negotiation to succeed, the
.Fa ssl
must have been initialized to client or server mode.
This is being done by calling
.Xr SSL_set_connect_state 3
or
.Xr SSL_set_accept_state 3
before the first call to an
.Xr SSL_read 3
or
.Fn SSL_write
function.
.Pp
If the underlying
.Vt BIO
is
.Em blocking ,
.Fn SSL_write
will only return once the write operation has been finished or an error
occurred, except when a renegotiation take place, in which case a
.Dv SSL_ERROR_WANT_READ
may occur.
This behaviour can be controlled with the
.Dv SSL_MODE_AUTO_RETRY
flag of the
.Xr SSL_CTX_set_mode 3
call.
.Pp
If the underlying
.Vt BIO
is
.Em non-blocking ,
.Fn SSL_write
will also return when the underlying
.Vt BIO
could not satisfy the needs of
.Fn SSL_write
to continue the operation.
In this case a call to
.Xr SSL_get_error 3
with the return value of
.Fn SSL_write
will yield
.Dv SSL_ERROR_WANT_READ
or
.Dv SSL_ERROR_WANT_WRITE .
As at any time a re-negotiation is possible, a call to
.Fn SSL_write
can also cause read operations!
The calling process then must repeat the call after taking appropriate action
to satisfy the needs of
.Fn SSL_write .
The action depends on the underlying
.Vt BIO .
When using a non-blocking socket, nothing is to be done, but
.Xr select 2
can be used to check for the required condition.
When using a buffering
.Vt BIO ,
like a
.Vt BIO
pair, data must be written into or retrieved out of the BIO before being able
to continue.
.Pp
.Fn SSL_write
will only return with success, when the complete contents of
.Fa buf
of length
.Fa num
have been written.
This default behaviour can be changed with the
.Dv SSL_MODE_ENABLE_PARTIAL_WRITE
option of
.Xr SSL_CTX_set_mode 3 .
When this flag is set,
.Fn SSL_write
will also return with success when a partial write has been successfully
completed.
In this case the
.Fn SSL_write
operation is considered completed.
The bytes are sent and a new
.Fn SSL_write
operation with a new buffer (with the already sent bytes removed) must be
started.
A partial write is performed with the size of a message block, which is 16kB
for SSLv3/TLSv1.
.Sh WARNING
When an
.Fn SSL_write
operation has to be repeated because of
.Dv SSL_ERROR_WANT_READ
or
.Dv SSL_ERROR_WANT_WRITE ,
it must be repeated with the same arguments.
.Pp
When calling
.Fn SSL_write
with
.Fa num Ns
=0 bytes to be sent the behaviour is undefined.
.Sh RETURN VALUES
The following return values can occur:
.Bl -tag -width Ds
.It >0
The write operation was successful.
The return value is the number of bytes actually written to the TLS/SSL
connection.
.It 0
The write operation was not successful.
Probably the underlying connection was closed.
Call
.Xr SSL_get_error 3
with the return value to find out whether an error occurred or the connection
was shut down cleanly
.Pq Dv SSL_ERROR_ZERO_RETURN .
.Pp
SSLv2 (deprecated) does not support a shutdown alert protocol, so it can only
be detected whether the underlying connection was closed.
It cannot be checked why the closure happened.
.It <0
The write operation was not successful, because either an error occurred or
action must be taken by the calling process.
Call
.Xr SSL_get_error 3
with the return value to find out the reason.
.El
.Sh SEE ALSO
.Xr bio 3 ,
.Xr ssl 3 ,
.Xr SSL_accept 3 ,
.Xr SSL_connect 3 ,
.Xr SSL_CTX_new 3 ,
.Xr SSL_CTX_set_mode 3 ,
.Xr SSL_get_error 3 ,
.Xr SSL_read 3 ,
.Xr SSL_set_connect_state 3