xref: /openssl/doc/man3/SSL_write.pod (revision 0f77b6f1)
1=pod
2
3=head1 NAME
4
5SSL_write_ex2, SSL_write_ex, SSL_write, SSL_sendfile, SSL_WRITE_FLAG_CONCLUDE -
6write bytes to a TLS/SSL connection
7
8=head1 SYNOPSIS
9
10 #include <openssl/ssl.h>
11
12 #define SSL_WRITE_FLAG_CONCLUDE
13
14 ossl_ssize_t SSL_sendfile(SSL *s, int fd, off_t offset, size_t size, int flags);
15 int SSL_write_ex2(SSL *s, const void *buf, size_t num,
16                   uint64_t flags,
17                   size_t *written);
18 int SSL_write_ex(SSL *s, const void *buf, size_t num, size_t *written);
19 int SSL_write(SSL *ssl, const void *buf, int num);
20
21=head1 DESCRIPTION
22
23SSL_write_ex() and SSL_write() write B<num> bytes from the buffer B<buf> into
24the specified B<ssl> connection. On success SSL_write_ex() will store the number
25of bytes written in B<*written>.
26
27SSL_write_ex2() functions similarly to SSL_write_ex() but can also accept
28optional flags which modify its behaviour. Calling SSL_write_ex2() with a
29I<flags> argument of 0 is exactly equivalent to calling SSL_write_ex().
30
31SSL_sendfile() writes B<size> bytes from offset B<offset> in the file
32descriptor B<fd> to the specified SSL connection B<s>. This function provides
33efficient zero-copy semantics. SSL_sendfile() is available only when
34Kernel TLS is enabled, which can be checked by calling BIO_get_ktls_send().
35It is provided here to allow users to maintain the same interface.
36The meaning of B<flags> is platform dependent.
37Currently, under Linux it is ignored.
38
39The I<flags> argument to SSL_write_ex2() can accept zero or more of the
40following flags. Note that which flags are supported will depend on the kind of
41SSL object and underlying protocol being used:
42
43=over 4
44
45=item B<SSL_WRITE_FLAG_CONCLUDE>
46
47This flag is only supported on QUIC stream SSL objects (or QUIC connection SSL
48objects with a default stream attached).
49
50If this flag is set, and the call to SSL_write_ex2() succeeds, and all of the
51data passed to the call is written (meaning that C<*written == num>), the
52relevant QUIC stream's send part is concluded automatically as though
53L<SSL_stream_conclude(3)> was called (causing transmission of a FIN for the
54stream).
55
56While using this flag is semantically equivalent to calling
57L<SSL_stream_conclude(3)> after a successful call to this function, using this
58flag enables greater efficiency than making these two API calls separately, as
59it enables the written stream data and the FIN flag indicating the end of the
60stream to be scheduled as part of the same QUIC STREAM frame and QUIC packet.
61
62Setting this flag does not cause a stream's send part to be concluded if not all
63of the data passed to the call was consumed.
64
65=back
66
67A call to SSL_write_ex2() fails if a flag is passed which is not supported or
68understood by the given SSL object. An application should determine if a flag is
69supported (for example, for B<SSL_WRITE_FLAG_CONCLUDE>, that a QUIC stream SSL
70object is being used) before attempting to use it.
71
72=head1 NOTES
73
74In the paragraphs below a "write function" is defined as one of either
75SSL_write_ex(), or SSL_write().
76
77If necessary, a write function will negotiate a TLS/SSL session, if not already
78explicitly performed by L<SSL_connect(3)> or L<SSL_accept(3)>. If the peer
79requests a re-negotiation, it will be performed transparently during
80the write function operation. The behaviour of the write functions depends on the
81underlying BIO.
82
83For the transparent negotiation to succeed, the B<ssl> must have been
84initialized to client or server mode. This is being done by calling
85L<SSL_set_connect_state(3)> or SSL_set_accept_state()
86before the first call to a write function.
87
88If the underlying BIO is B<blocking>, the write functions will only return, once
89the write operation has been finished or an error occurred.
90
91If the underlying BIO is B<nonblocking> the write functions will also return
92when the underlying BIO could not satisfy the needs of the function to continue
93the operation. In this case a call to L<SSL_get_error(3)> with the
94return value of the write function will yield B<SSL_ERROR_WANT_READ>
95or B<SSL_ERROR_WANT_WRITE>. As at any time a re-negotiation is possible, a
96call to a write function can also cause read operations! The calling process
97then must repeat the call after taking appropriate action to satisfy the needs
98of the write function. The action depends on the underlying BIO. When using a
99nonblocking socket, nothing is to be done, but select() can be used to check
100for the required condition. When using a buffering BIO, like a BIO pair, data
101must be written into or retrieved out of the BIO before being able to continue.
102
103The write functions will only return with success when the complete contents of
104B<buf> of length B<num> has been written. This default behaviour can be changed
105with the SSL_MODE_ENABLE_PARTIAL_WRITE option of L<SSL_CTX_set_mode(3)>. When
106this flag is set the write functions will also return with success when a
107partial write has been successfully completed. In this case the write function
108operation is considered completed. The bytes are sent and a new write call with
109a new buffer (with the already sent bytes removed) must be started. A partial
110write is performed with the size of a message block, which is 16kB.
111
112When used with a QUIC SSL object, calling an I/O function such as SSL_write()
113allows internal network event processing to be performed. It is important that
114this processing is performed regularly. If an application is not using thread
115assisted mode, an application should ensure that an I/O function such as
116SSL_write() is called regularly, or alternatively ensure that SSL_handle_events()
117is called regularly. See L<openssl-quic(7)> and L<SSL_handle_events(3)> for more
118information.
119
120=head1 WARNINGS
121
122When a write function call has to be repeated because L<SSL_get_error(3)>
123returned B<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE>, it must be repeated
124with the same arguments.
125The data that was passed might have been partially processed.
126When B<SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER> was set using L<SSL_CTX_set_mode(3)>
127the pointer can be different, but the data and length should still be the same.
128
129You should not call SSL_write() with num=0, it will return an error.
130SSL_write_ex() can be called with num=0, but will not send application data to
131the peer.
132
133=head1 RETURN VALUES
134
135SSL_write_ex() and SSL_write_ex2() return 1 for success or 0 for failure.
136Success means that all requested application data bytes have been written to the
137SSL connection or, if SSL_MODE_ENABLE_PARTIAL_WRITE is in use, at least 1
138application data byte has been written to the SSL connection. Failure means that
139not all the requested bytes have been written yet (if
140SSL_MODE_ENABLE_PARTIAL_WRITE is not in use) or no bytes could be written to the
141SSL connection (if SSL_MODE_ENABLE_PARTIAL_WRITE is in use). Failures can be
142retryable (e.g. the network write buffer has temporarily filled up) or
143non-retryable (e.g. a fatal network error). In the event of a failure call
144L<SSL_get_error(3)> to find out the reason which indicates whether the call is
145retryable or not.
146
147For SSL_write() the following return values can occur:
148
149=over 4
150
151=item E<gt> 0
152
153The write operation was successful, the return value is the number of
154bytes actually written to the TLS/SSL connection.
155
156=item Z<><= 0
157
158The write operation was not successful, because either the connection was
159closed, an error occurred or action must be taken by the calling process.
160Call SSL_get_error() with the return value B<ret> to find out the reason.
161
162Old documentation indicated a difference between 0 and -1, and that -1 was
163retryable.
164You should instead call SSL_get_error() to find out if it's retryable.
165
166=back
167
168For SSL_sendfile(), the following return values can occur:
169
170=over 4
171
172=item Z<>>= 0
173
174The write operation was successful, the return value is the number
175of bytes of the file written to the TLS/SSL connection. The return
176value can be less than B<size> for a partial write.
177
178=item E<lt> 0
179
180The write operation was not successful, because either the connection was
181closed, an error occurred or action must be taken by the calling process.
182Call SSL_get_error() with the return value to find out the reason.
183
184=back
185
186=head1 SEE ALSO
187
188L<SSL_get_error(3)>, L<SSL_read_ex(3)>, L<SSL_read(3)>
189L<SSL_CTX_set_mode(3)>, L<SSL_CTX_new(3)>,
190L<SSL_connect(3)>, L<SSL_accept(3)>
191L<SSL_set_connect_state(3)>, L<BIO_ctrl(3)>,
192L<ssl(7)>, L<bio(7)>
193
194=head1 HISTORY
195
196The SSL_write_ex() function was added in OpenSSL 1.1.1.
197The SSL_sendfile() function was added in OpenSSL 3.0.
198The SSL_write_ex2() function was added in OpenSSL 3.3.
199
200=head1 COPYRIGHT
201
202Copyright 2000-2024 The OpenSSL Project Authors. All Rights Reserved.
203
204Licensed under the Apache License 2.0 (the "License").  You may not use
205this file except in compliance with the License.  You can obtain a copy
206in the file LICENSE in the source distribution or at
207L<https://www.openssl.org/source/license.html>.
208
209=cut
210