summaryrefslogtreecommitdiff
path: root/src/lib/libssl/man/SSL_write.3
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--src/lib/libssl/man/SSL_write.3249
1 files changed, 0 insertions, 249 deletions
diff --git a/src/lib/libssl/man/SSL_write.3 b/src/lib/libssl/man/SSL_write.3
deleted file mode 100644
index 2c6fbcef08..0000000000
--- a/src/lib/libssl/man/SSL_write.3
+++ /dev/null
@@ -1,249 +0,0 @@
1.\" $OpenBSD: SSL_write.3,v 1.7 2021/10/24 15:10:13 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: October 24 2021 $
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.In openssl/ssl.h
63.Ft int
64.Fn SSL_write_ex "SSL *ssl" "const void *buf" "size_t num" "size_t *written"
65.Ft int
66.Fn SSL_write "SSL *ssl" "const void *buf" "int num"
67.Sh DESCRIPTION
68.Fn SSL_write_ex
69and
70.Fn SSL_write
71write
72.Fa num
73bytes from the buffer
74.Fa buf
75into the specified
76.Fa ssl
77connection.
78On success
79.Fn SSL_write_ex
80stores the number of bytes written in
81.Pf * Fa written .
82.Pp
83In the following,
84.Fn SSL_write_ex
85and
86.Fn SSL_write
87are called
88.Dq write functions .
89.Pp
90If necessary, a write function negotiates a TLS session,
91if not already explicitly performed by
92.Xr SSL_connect 3
93or
94.Xr SSL_accept 3 .
95If the peer requests a re-negotiation,
96it will be performed transparently during the
97write function operation.
98The behaviour of the write functions depends on the underlying
99.Vt BIO .
100.Pp
101For the transparent negotiation to succeed, the
102.Fa ssl
103must have been initialized to client or server mode.
104This is done by calling
105.Xr SSL_set_connect_state 3
106or
107.Xr SSL_set_accept_state 3
108before the first call to a write function.
109.Pp
110If the underlying
111.Vt BIO
112is
113.Em blocking ,
114the write function
115will only return once the write operation has been finished or an error
116occurred, except when a renegotiation takes place, in which case a
117.Dv SSL_ERROR_WANT_READ
118may occur.
119This behaviour can be controlled with the
120.Dv SSL_MODE_AUTO_RETRY
121flag of the
122.Xr SSL_CTX_set_mode 3
123call.
124.Pp
125If the underlying
126.Vt BIO
127is
128.Em non-blocking ,
129the write function will also return when the underlying
130.Vt BIO
131could not satisfy the needs of the function to continue the operation.
132In this case a call to
133.Xr SSL_get_error 3
134with the return value of the write function will yield
135.Dv SSL_ERROR_WANT_READ
136or
137.Dv SSL_ERROR_WANT_WRITE .
138As at any time a re-negotiation is possible, a call to
139a write function can also cause read operations.
140The calling process then must repeat the call after taking appropriate action
141to satisfy the needs of the write function.
142The action depends on the underlying
143.Vt BIO .
144When using a non-blocking socket, nothing is to be done, but
145.Xr select 2
146can be used to check for the required condition.
147When using a buffering
148.Vt BIO ,
149like a
150.Vt BIO
151pair, data must be written into or retrieved out of the BIO before being able
152to continue.
153.Pp
154The write functions
155will only return with success when the complete contents of
156.Fa buf
157of length
158.Fa num
159have been written.
160This default behaviour can be changed with the
161.Dv SSL_MODE_ENABLE_PARTIAL_WRITE
162option of
163.Xr SSL_CTX_set_mode 3 .
164When this flag is set, the write functions will also return with
165success when a partial write has been successfully completed.
166In this case the write function operation is considered completed.
167The bytes are sent and a new write call with a new buffer (with the
168already sent bytes removed) must be started.
169A partial write is performed with the size of a message block,
170which is 16kB.
171.Pp
172When a write function call has to be repeated because
173.Xr SSL_get_error 3
174returned
175.Dv SSL_ERROR_WANT_READ
176or
177.Dv SSL_ERROR_WANT_WRITE ,
178it must be repeated with the same arguments.
179.Pp
180When calling
181.Fn SSL_write
182with
183.Fa num Ns =0
184bytes to be sent, the behaviour is undefined.
185.Fn SSL_write_ex
186can be called with
187.Fa num Ns =0 ,
188but will not send application data to the peer.
189.Sh RETURN VALUES
190.Fn SSL_write_ex
191returns 1 for success or 0 for failure.
192Success means that all requested application data bytes have been
193written to the TLS connection or, if
194.Dv SSL_MODE_ENABLE_PARTIAL_WRITE
195is in use, at least one application data byte has been written
196to the TLS connection.
197Failure means that not all the requested bytes have been written yet (if
198.Dv SSL_MODE_ENABLE_PARTIAL_WRITE
199is not in use) or no bytes could be written to the TLS connection (if
200.Dv SSL_MODE_ENABLE_PARTIAL_WRITE
201is in use).
202Failures can be retryable (e.g. the network write buffer has temporarily
203filled up) or non-retryable (e.g. a fatal network error).
204In the event of a failure, call
205.Xr SSL_get_error 3
206to find out the reason
207which indicates whether the call is retryable or not.
208.Pp
209For
210.Fn SSL_write ,
211the following return values can occur:
212.Bl -tag -width Ds
213.It >0
214The write operation was successful.
215The return value is the number of bytes actually written to the TLS
216connection.
217.It 0
218The write operation was not successful.
219Probably the underlying connection was closed.
220Call
221.Xr SSL_get_error 3
222with the return value to find out whether an error occurred or the connection
223was shut down cleanly
224.Pq Dv SSL_ERROR_ZERO_RETURN .
225.It <0
226The write operation was not successful, because either an error occurred or
227action must be taken by the calling process.
228Call
229.Xr SSL_get_error 3
230with the return value to find out the reason.
231.El
232.Sh SEE ALSO
233.Xr BIO_new 3 ,
234.Xr ssl 3 ,
235.Xr SSL_accept 3 ,
236.Xr SSL_connect 3 ,
237.Xr SSL_CTX_new 3 ,
238.Xr SSL_CTX_set_mode 3 ,
239.Xr SSL_get_error 3 ,
240.Xr SSL_read 3 ,
241.Xr SSL_set_connect_state 3
242.Sh HISTORY
243.Fn SSL_write
244appeared in SSLeay 0.4 or earlier and has been available since
245.Ox 2.4 .
246.Pp
247.Fn SSL_write_ex
248first appeared in OpenSSL 1.1.1 and has been available since
249.Ox 7.1 .
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-04-28 22:39:28 +0000