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