1e71b7053SJung-uk Kim=pod 2e71b7053SJung-uk Kim 3e71b7053SJung-uk Kim=head1 NAME 4e71b7053SJung-uk Kim 5aa906e2aSJohn BaldwinSSL_write_ex, SSL_write, SSL_sendfile - write bytes to a TLS/SSL connection 6e71b7053SJung-uk Kim 7e71b7053SJung-uk Kim=head1 SYNOPSIS 8e71b7053SJung-uk Kim 9e71b7053SJung-uk Kim #include <openssl/ssl.h> 10e71b7053SJung-uk Kim 11aa906e2aSJohn Baldwin ossl_ssize_t SSL_sendfile(SSL *s, int fd, off_t offset, size_t size, int flags); 12e71b7053SJung-uk Kim int SSL_write_ex(SSL *s, const void *buf, size_t num, size_t *written); 13e71b7053SJung-uk Kim int SSL_write(SSL *ssl, const void *buf, int num); 14e71b7053SJung-uk Kim 15e71b7053SJung-uk Kim=head1 DESCRIPTION 16e71b7053SJung-uk Kim 17e71b7053SJung-uk KimSSL_write_ex() and SSL_write() write B<num> bytes from the buffer B<buf> into 18e71b7053SJung-uk Kimthe specified B<ssl> connection. On success SSL_write_ex() will store the number 19e71b7053SJung-uk Kimof bytes written in B<*written>. 20e71b7053SJung-uk Kim 21aa906e2aSJohn BaldwinSSL_sendfile() writes B<size> bytes from offset B<offset> in the file 22aa906e2aSJohn Baldwindescriptor B<fd> to the specified SSL connection B<s>. This function provides 23aa906e2aSJohn Baldwinefficient zero-copy semantics. SSL_sendfile() is available only when 24aa906e2aSJohn BaldwinKernel TLS is enabled, which can be checked by calling BIO_get_ktls_send(). 25aa906e2aSJohn BaldwinIt is provided here to allow users to maintain the same interface. 26aa906e2aSJohn BaldwinThe meaning of B<flags> is platform dependent. 27aa906e2aSJohn BaldwinCurrently, under Linux it is ignored. 28aa906e2aSJohn Baldwin 29e71b7053SJung-uk Kim=head1 NOTES 30e71b7053SJung-uk Kim 31e71b7053SJung-uk KimIn the paragraphs below a "write function" is defined as one of either 32e71b7053SJung-uk KimSSL_write_ex(), or SSL_write(). 33e71b7053SJung-uk Kim 34e71b7053SJung-uk KimIf necessary, a write function will negotiate a TLS/SSL session, if not already 35e71b7053SJung-uk Kimexplicitly performed by L<SSL_connect(3)> or L<SSL_accept(3)>. If the peer 36e71b7053SJung-uk Kimrequests a re-negotiation, it will be performed transparently during 37e71b7053SJung-uk Kimthe write function operation. The behaviour of the write functions depends on the 38e71b7053SJung-uk Kimunderlying BIO. 39e71b7053SJung-uk Kim 40e71b7053SJung-uk KimFor the transparent negotiation to succeed, the B<ssl> must have been 41e71b7053SJung-uk Kiminitialized to client or server mode. This is being done by calling 42e71b7053SJung-uk KimL<SSL_set_connect_state(3)> or SSL_set_accept_state() 43e71b7053SJung-uk Kimbefore the first call to a write function. 44e71b7053SJung-uk Kim 45e71b7053SJung-uk KimIf the underlying BIO is B<blocking>, the write functions will only return, once 46e71b7053SJung-uk Kimthe write operation has been finished or an error occurred. 47e71b7053SJung-uk Kim 4858f35182SJung-uk KimIf the underlying BIO is B<nonblocking> the write functions will also return 49e71b7053SJung-uk Kimwhen the underlying BIO could not satisfy the needs of the function to continue 50e71b7053SJung-uk Kimthe operation. In this case a call to L<SSL_get_error(3)> with the 51e71b7053SJung-uk Kimreturn value of the write function will yield B<SSL_ERROR_WANT_READ> 52e71b7053SJung-uk Kimor B<SSL_ERROR_WANT_WRITE>. As at any time a re-negotiation is possible, a 53e71b7053SJung-uk Kimcall to a write function can also cause read operations! The calling process 54e71b7053SJung-uk Kimthen must repeat the call after taking appropriate action to satisfy the needs 55e71b7053SJung-uk Kimof the write function. The action depends on the underlying BIO. When using a 5658f35182SJung-uk Kimnonblocking socket, nothing is to be done, but select() can be used to check 57e71b7053SJung-uk Kimfor the required condition. When using a buffering BIO, like a BIO pair, data 58e71b7053SJung-uk Kimmust be written into or retrieved out of the BIO before being able to continue. 59e71b7053SJung-uk Kim 60e71b7053SJung-uk KimThe write functions will only return with success when the complete contents of 61e71b7053SJung-uk KimB<buf> of length B<num> has been written. This default behaviour can be changed 62e71b7053SJung-uk Kimwith the SSL_MODE_ENABLE_PARTIAL_WRITE option of L<SSL_CTX_set_mode(3)>. When 63e71b7053SJung-uk Kimthis flag is set the write functions will also return with success when a 64e71b7053SJung-uk Kimpartial write has been successfully completed. In this case the write function 65e71b7053SJung-uk Kimoperation is considered completed. The bytes are sent and a new write call with 66e71b7053SJung-uk Kima new buffer (with the already sent bytes removed) must be started. A partial 67e71b7053SJung-uk Kimwrite is performed with the size of a message block, which is 16kB. 68e71b7053SJung-uk Kim 69da327cd2SJung-uk Kim=head1 WARNINGS 70e71b7053SJung-uk Kim 71e71b7053SJung-uk KimWhen a write function call has to be repeated because L<SSL_get_error(3)> 72e71b7053SJung-uk Kimreturned B<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE>, it must be repeated 73e71b7053SJung-uk Kimwith the same arguments. 74e71b7053SJung-uk KimThe data that was passed might have been partially processed. 75e71b7053SJung-uk KimWhen B<SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER> was set using L<SSL_CTX_set_mode(3)> 76e71b7053SJung-uk Kimthe pointer can be different, but the data and length should still be the same. 77e71b7053SJung-uk Kim 78e71b7053SJung-uk KimYou should not call SSL_write() with num=0, it will return an error. 79e71b7053SJung-uk KimSSL_write_ex() can be called with num=0, but will not send application data to 80e71b7053SJung-uk Kimthe peer. 81e71b7053SJung-uk Kim 82e71b7053SJung-uk Kim=head1 RETURN VALUES 83e71b7053SJung-uk Kim 84e71b7053SJung-uk KimSSL_write_ex() will return 1 for success or 0 for failure. Success means that 85e71b7053SJung-uk Kimall requested application data bytes have been written to the SSL connection or, 86e71b7053SJung-uk Kimif SSL_MODE_ENABLE_PARTIAL_WRITE is in use, at least 1 application data byte has 87e71b7053SJung-uk Kimbeen written to the SSL connection. Failure means that not all the requested 88e71b7053SJung-uk Kimbytes have been written yet (if SSL_MODE_ENABLE_PARTIAL_WRITE is not in use) or 89e71b7053SJung-uk Kimno bytes could be written to the SSL connection (if 90e71b7053SJung-uk KimSSL_MODE_ENABLE_PARTIAL_WRITE is in use). Failures can be retryable (e.g. the 91e71b7053SJung-uk Kimnetwork write buffer has temporarily filled up) or non-retryable (e.g. a fatal 92e71b7053SJung-uk Kimnetwork error). In the event of a failure call L<SSL_get_error(3)> to find out 93e71b7053SJung-uk Kimthe reason which indicates whether the call is retryable or not. 94e71b7053SJung-uk Kim 95e71b7053SJung-uk KimFor SSL_write() the following return values can occur: 96e71b7053SJung-uk Kim 97e71b7053SJung-uk Kim=over 4 98e71b7053SJung-uk Kim 99e71b7053SJung-uk Kim=item E<gt> 0 100e71b7053SJung-uk Kim 101e71b7053SJung-uk KimThe write operation was successful, the return value is the number of 102e71b7053SJung-uk Kimbytes actually written to the TLS/SSL connection. 103e71b7053SJung-uk Kim 104e71b7053SJung-uk Kim=item Z<><= 0 105e71b7053SJung-uk Kim 106e71b7053SJung-uk KimThe write operation was not successful, because either the connection was 107e71b7053SJung-uk Kimclosed, an error occurred or action must be taken by the calling process. 108e71b7053SJung-uk KimCall SSL_get_error() with the return value B<ret> to find out the reason. 109e71b7053SJung-uk Kim 110e71b7053SJung-uk KimOld documentation indicated a difference between 0 and -1, and that -1 was 111e71b7053SJung-uk Kimretryable. 112e71b7053SJung-uk KimYou should instead call SSL_get_error() to find out if it's retryable. 113e71b7053SJung-uk Kim 114e71b7053SJung-uk Kim=back 115e71b7053SJung-uk Kim 116aa906e2aSJohn BaldwinFor SSL_sendfile(), the following return values can occur: 117aa906e2aSJohn Baldwin 118aa906e2aSJohn Baldwin=over 4 119aa906e2aSJohn Baldwin 120aa906e2aSJohn Baldwin=item Z<>>= 0 121aa906e2aSJohn Baldwin 122aa906e2aSJohn BaldwinThe write operation was successful, the return value is the number 1239b2f020cSOleksandr Tymoshenkoof bytes of the file written to the TLS/SSL connection. The return 1249b2f020cSOleksandr Tymoshenkovalue can be less than B<size> for a partial write. 125aa906e2aSJohn Baldwin 126aa906e2aSJohn Baldwin=item E<lt> 0 127aa906e2aSJohn Baldwin 128aa906e2aSJohn BaldwinThe write operation was not successful, because either the connection was 129b077aed3SPierre Proncheryclosed, an error occurred or action must be taken by the calling process. 130aa906e2aSJohn BaldwinCall SSL_get_error() with the return value to find out the reason. 131aa906e2aSJohn Baldwin 132aa906e2aSJohn Baldwin=back 133aa906e2aSJohn Baldwin 134e71b7053SJung-uk Kim=head1 SEE ALSO 135e71b7053SJung-uk Kim 136e71b7053SJung-uk KimL<SSL_get_error(3)>, L<SSL_read_ex(3)>, L<SSL_read(3)> 137e71b7053SJung-uk KimL<SSL_CTX_set_mode(3)>, L<SSL_CTX_new(3)>, 138e71b7053SJung-uk KimL<SSL_connect(3)>, L<SSL_accept(3)> 139aa906e2aSJohn BaldwinL<SSL_set_connect_state(3)>, L<BIO_ctrl(3)>, 140e71b7053SJung-uk KimL<ssl(7)>, L<bio(7)> 141e71b7053SJung-uk Kim 142610a21fdSJung-uk Kim=head1 HISTORY 143610a21fdSJung-uk Kim 144610a21fdSJung-uk KimThe SSL_write_ex() function was added in OpenSSL 1.1.1. 145b077aed3SPierre ProncheryThe SSL_sendfile() function was added in OpenSSL 3.0. 146610a21fdSJung-uk Kim 147e71b7053SJung-uk Kim=head1 COPYRIGHT 148e71b7053SJung-uk Kim 149b077aed3SPierre ProncheryCopyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved. 150e71b7053SJung-uk Kim 151b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 152e71b7053SJung-uk Kimthis file except in compliance with the License. You can obtain a copy 153e71b7053SJung-uk Kimin the file LICENSE in the source distribution or at 154e71b7053SJung-uk KimL<https://www.openssl.org/source/license.html>. 155e71b7053SJung-uk Kim 156e71b7053SJung-uk Kim=cut 157