jcs.org
jcs's openbsd hax
openbsd
1.\" $OpenBSD: SSL_write.3,v 1.8 2025/06/08 22:52:00 schwarze Exp $
2.\" full merge up to: OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
3.\" partial merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100
4.\"
5.\" This file was written by Lutz Jaenicke <jaenicke@openssl.org>
6.\" and Matt Caswell <matt@openssl.org>.
7.\" Copyright (c) 2000, 2001, 2002, 2016 The OpenSSL Project.
8.\" All rights reserved.
9.\"
10.\" Redistribution and use in source and binary forms, with or without
11.\" modification, are permitted provided that the following conditions
12.\" are met:
13.\"
14.\" 1. Redistributions of source code must retain the above copyright
15.\" notice, this list of conditions and the following disclaimer.
16.\"
17.\" 2. Redistributions in binary form must reproduce the above copyright
18.\" notice, this list of conditions and the following disclaimer in
19.\" the documentation and/or other materials provided with the
20.\" distribution.
21.\"
22.\" 3. All advertising materials mentioning features or use of this
23.\" software must display the following acknowledgment:
24.\" "This product includes software developed by the OpenSSL Project
25.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
26.\"
27.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
28.\" endorse or promote products derived from this software without
29.\" prior written permission. For written permission, please contact
30.\" openssl-core@openssl.org.
31.\"
32.\" 5. Products derived from this software may not be called "OpenSSL"
33.\" nor may "OpenSSL" appear in their names without prior written
34.\" permission of the OpenSSL Project.
35.\"
36.\" 6. Redistributions of any form whatsoever must retain the following
37.\" acknowledgment:
38.\" "This product includes software developed by the OpenSSL Project
39.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
40.\"
41.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
42.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
43.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
44.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
45.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
46.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
47.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
48.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
49.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
50.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
51.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
52.\" OF THE POSSIBILITY OF SUCH DAMAGE.
53.\"
54.Dd $Mdocdate: June 8 2025 $
55.Dt SSL_WRITE 3
56.Os
57.Sh NAME
58.Nm SSL_write_ex ,
59.Nm SSL_write
60.Nd write bytes to a TLS connection
61.Sh SYNOPSIS
62.Lb libssl libcrypto
63.In openssl/ssl.h
64.Ft int
65.Fn SSL_write_ex "SSL *ssl" "const void *buf" "size_t num" "size_t *written"
66.Ft int
67.Fn SSL_write "SSL *ssl" "const void *buf" "int num"
68.Sh DESCRIPTION
69.Fn SSL_write_ex
70and
71.Fn SSL_write
72write
73.Fa num
74bytes from the buffer
75.Fa buf
76into the specified
77.Fa ssl
78connection.
79On success
80.Fn SSL_write_ex
81stores the number of bytes written in
82.Pf * Fa written .
83.Pp
84In the following,
85.Fn SSL_write_ex
86and
87.Fn SSL_write
88are called
89.Dq write functions .
90.Pp
91If necessary, a write function negotiates a TLS session,
92if not already explicitly performed by
93.Xr SSL_connect 3
94or
95.Xr SSL_accept 3 .
96If the peer requests a re-negotiation,
97it will be performed transparently during the
98write function operation.
99The behaviour of the write functions depends on the underlying
100.Vt BIO .
101.Pp
102For the transparent negotiation to succeed, the
103.Fa ssl
104must have been initialized to client or server mode.
105This is done by calling
106.Xr SSL_set_connect_state 3
107or
108.Xr SSL_set_accept_state 3
109before the first call to a write function.
110.Pp
111If the underlying
112.Vt BIO
113is
114.Em blocking ,
115the write function
116will only return once the write operation has been finished or an error
117occurred, except when a renegotiation takes place, in which case a
118.Dv SSL_ERROR_WANT_READ
119may occur.
120This behaviour can be controlled with the
121.Dv SSL_MODE_AUTO_RETRY
122flag of the
123.Xr SSL_CTX_set_mode 3
124call.
125.Pp
126If the underlying
127.Vt BIO
128is
129.Em non-blocking ,
130the write function will also return when the underlying
131.Vt BIO
132could not satisfy the needs of the function to continue the operation.
133In this case a call to
134.Xr SSL_get_error 3
135with the return value of the write function will yield
136.Dv SSL_ERROR_WANT_READ
137or
138.Dv SSL_ERROR_WANT_WRITE .
139As at any time a re-negotiation is possible, a call to
140a write function can also cause read operations.
141The calling process then must repeat the call after taking appropriate action
142to satisfy the needs of the write function.
143The action depends on the underlying
144.Vt BIO .
145When using a non-blocking socket, nothing is to be done, but
146.Xr select 2
147can be used to check for the required condition.
148When using a buffering
149.Vt BIO ,
150like a
151.Vt BIO
152pair, data must be written into or retrieved out of the BIO before being able
153to continue.
154.Pp
155The write functions
156will only return with success when the complete contents of
157.Fa buf
158of length
159.Fa num
160have been written.
161This default behaviour can be changed with the
162.Dv SSL_MODE_ENABLE_PARTIAL_WRITE
163option of
164.Xr SSL_CTX_set_mode 3 .
165When this flag is set, the write functions will also return with
166success when a partial write has been successfully completed.
167In this case the write function operation is considered completed.
168The bytes are sent and a new write call with a new buffer (with the
169already sent bytes removed) must be started.
170A partial write is performed with the size of a message block,
171which is 16kB.
172.Pp
173When a write function call has to be repeated because
174.Xr SSL_get_error 3
175returned
176.Dv SSL_ERROR_WANT_READ
177or
178.Dv SSL_ERROR_WANT_WRITE ,
179it must be repeated with the same arguments.
180.Pp
181When calling
182.Fn SSL_write
183with
184.Fa num Ns =0
185bytes to be sent, the behaviour is undefined.
186.Fn SSL_write_ex
187can be called with
188.Fa num Ns =0 ,
189but will not send application data to the peer.
190.Sh RETURN VALUES
191.Fn SSL_write_ex
192returns 1 for success or 0 for failure.
193Success means that all requested application data bytes have been
194written to the TLS connection or, if
195.Dv SSL_MODE_ENABLE_PARTIAL_WRITE
196is in use, at least one application data byte has been written
197to the TLS connection.
198Failure means that not all the requested bytes have been written yet (if
199.Dv SSL_MODE_ENABLE_PARTIAL_WRITE
200is not in use) or no bytes could be written to the TLS connection (if
201.Dv SSL_MODE_ENABLE_PARTIAL_WRITE
202is in use).
203Failures can be retryable (e.g. the network write buffer has temporarily
204filled up) or non-retryable (e.g. a fatal network error).
205In the event of a failure, call
206.Xr SSL_get_error 3
207to find out the reason
208which indicates whether the call is retryable or not.
209.Pp
210For
211.Fn SSL_write ,
212the following return values can occur:
213.Bl -tag -width Ds
214.It >0
215The write operation was successful.
216The return value is the number of bytes actually written to the TLS
217connection.
218.It 0
219The write operation was not successful.
220Probably the underlying connection was closed.
221Call
222.Xr SSL_get_error 3
223with the return value to find out whether an error occurred or the connection
224was shut down cleanly
225.Pq Dv SSL_ERROR_ZERO_RETURN .
226.It <0
227The write operation was not successful, because either an error occurred or
228action must be taken by the calling process.
229Call
230.Xr SSL_get_error 3
231with the return value to find out the reason.
232.El
233.Sh SEE ALSO
234.Xr BIO_new 3 ,
235.Xr ssl 3 ,
236.Xr SSL_accept 3 ,
237.Xr SSL_connect 3 ,
238.Xr SSL_CTX_new 3 ,
239.Xr SSL_CTX_set_mode 3 ,
240.Xr SSL_get_error 3 ,
241.Xr SSL_read 3 ,
242.Xr SSL_set_connect_state 3
243.Sh HISTORY
244.Fn SSL_write
245appeared in SSLeay 0.4 or earlier and has been available since
246.Ox 2.4 .
247.Pp
248.Fn SSL_write_ex
249first appeared in OpenSSL 1.1.1 and has been available since
250.Ox 7.1 .