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. 198 199=head1 COPYRIGHT 200 201Copyright 2000-2024 The OpenSSL Project Authors. All Rights Reserved. 202 203Licensed under the Apache License 2.0 (the "License"). You may not use 204this file except in compliance with the License. You can obtain a copy 205in the file LICENSE in the source distribution or at 206L<https://www.openssl.org/source/license.html>. 207 208=cut 209
