]>
Commit | Line | Data |
---|---|---|
cc99526d RL |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
7714dc5e | 5 | SSL_write_ex, SSL_write - write bytes to a TLS/SSL connection |
cc99526d RL |
6 | |
7 | =head1 SYNOPSIS | |
8 | ||
9 | #include <openssl/ssl.h> | |
10 | ||
7714dc5e | 11 | int SSL_write_ex(SSL *s, const void *buf, size_t num, size_t *written); |
e34cfcf7 | 12 | int SSL_write(SSL *ssl, const void *buf, int num); |
cc99526d RL |
13 | |
14 | =head1 DESCRIPTION | |
15 | ||
7714dc5e MC |
16 | SSL_write_ex() and SSL_write() write B<num> bytes from the buffer B<buf> into |
17 | the specified B<ssl> connection. On success SSL_write_ex() will store the number | |
18 | of bytes written in B<*written>. | |
c19b6c92 RL |
19 | |
20 | =head1 NOTES | |
21 | ||
6782e5fd MC |
22 | In the paragraphs below a "write function" is defined as one of either |
23 | SSL_write_ex(), or SSL_write(). | |
24 | ||
25 | If necessary, a write function will negotiate a TLS/SSL session, if not already | |
26 | explicitly performed by L<SSL_connect(3)> or L<SSL_accept(3)>. If the peer | |
27 | requests a re-negotiation, it will be performed transparently during | |
27b138e9 | 28 | the write function operation. The behaviour of the write functions depends on the |
6782e5fd | 29 | underlying BIO. |
cc99526d | 30 | |
b72ff470 | 31 | For the transparent negotiation to succeed, the B<ssl> must have been |
7abe76e1 | 32 | initialized to client or server mode. This is being done by calling |
9b86974e | 33 | L<SSL_set_connect_state(3)> or SSL_set_accept_state() |
6782e5fd | 34 | before the first call to a write function. |
b72ff470 | 35 | |
6782e5fd | 36 | If the underlying BIO is B<blocking>, the write functions will only return, once |
57fd5170 | 37 | the write operation has been finished or an error occurred. |
cc99526d | 38 | |
6782e5fd MC |
39 | If the underlying BIO is B<non-blocking> the write functions will also return |
40 | when the underlying BIO could not satisfy the needs of the function to continue | |
41 | the operation. In this case a call to L<SSL_get_error(3)> with the | |
42 | return value of the write function will yield B<SSL_ERROR_WANT_READ> | |
7714dc5e | 43 | or B<SSL_ERROR_WANT_WRITE>. As at any time a re-negotiation is possible, a |
6782e5fd MC |
44 | call to a write function can also cause read operations! The calling process |
45 | then must repeat the call after taking appropriate action to satisfy the needs | |
46 | of the write function. The action depends on the underlying BIO. When using a | |
47 | non-blocking socket, nothing is to be done, but select() can be used to check | |
48 | for the required condition. When using a buffering BIO, like a BIO pair, data | |
49 | must be written into or retrieved out of the BIO before being able to continue. | |
50 | ||
51 | The write functions will only return with success when the complete contents of | |
52 | B<buf> of length B<num> has been written. This default behaviour can be changed | |
53 | with the SSL_MODE_ENABLE_PARTIAL_WRITE option of L<SSL_CTX_set_mode(3)>. When | |
54 | this flag is set the write functions will also return with success when a | |
55 | partial write has been successfully completed. In this case the write function | |
56 | operation is considered completed. The bytes are sent and a new write call with | |
57 | a new buffer (with the already sent bytes removed) must be started. A partial | |
58 | write is performed with the size of a message block, which is 16kB. | |
4b3270f7 | 59 | |
4aa4f333 | 60 | =head1 WARNING |
c19b6c92 | 61 | |
6782e5fd MC |
62 | When a write function call has to be repeated because L<SSL_get_error(3)> |
63 | returned B<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE>, it must be repeated | |
c19b6c92 | 64 | with the same arguments. |
57fd5170 KR |
65 | The data that was passed might have been partially processed. |
66 | When B<SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER> was set using L<SSL_CTX_set_mode(3)> | |
67 | the pointer can be different, but the data and length should still be the same. | |
c19b6c92 | 68 | |
57fd5170 KR |
69 | You should not call SSL_write() with num=0, it will return an error. |
70 | SSL_write_ex() can be called with num=0, but will not send application data to | |
71 | the peer. | |
20adcfa0 | 72 | |
cc99526d RL |
73 | =head1 RETURN VALUES |
74 | ||
740bfeba MC |
75 | SSL_write_ex() will return 1 for success or 0 for failure. Success means that |
76 | all requested application data bytes have been written to the SSL connection or, | |
77 | if SSL_MODE_ENABLE_PARTIAL_WRITE is in use, at least 1 application data byte has | |
78 | been written to the SSL connection. Failure means that not all the requested | |
79 | bytes have been written yet (if SSL_MODE_ENABLE_PARTIAL_WRITE is not in use) or | |
80 | no bytes could be written to the SSL connection (if | |
81 | SSL_MODE_ENABLE_PARTIAL_WRITE is in use). Failures can be retryable (e.g. the | |
82 | network write buffer has temporarily filled up) or non-retryable (e.g. a fatal | |
83 | network error). In the event of a failure call L<SSL_get_error(3)> to find out | |
ed9fa2c7 | 84 | the reason which indicates whether the call is retryable or not. |
7714dc5e MC |
85 | |
86 | For SSL_write() the following return values can occur: | |
cc99526d RL |
87 | |
88 | =over 4 | |
89 | ||
beacb0f0 | 90 | =item E<gt> 0 |
cc99526d | 91 | |
1e4e5492 UM |
92 | The write operation was successful, the return value is the number of |
93 | bytes actually written to the TLS/SSL connection. | |
cc99526d | 94 | |
beacb0f0 | 95 | =item Z<><= 0 |
cc99526d | 96 | |
beacb0f0 KR |
97 | The write operation was not successful, because either the connection was |
98 | closed, an error occurred or action must be taken by the calling process. | |
99 | Call SSL_get_error() with the return value B<ret> to find out the reason. | |
d93eb21c | 100 | |
beacb0f0 KR |
101 | Old documentation indicated a difference between 0 and -1, and that -1 was |
102 | retryable. | |
103 | You should instead call SSL_get_error() to find out if it's retryable. | |
cc99526d RL |
104 | |
105 | =back | |
106 | ||
57fd5170 KR |
107 | =head1 HISTORY |
108 | ||
109 | SSL_write_ex() was added in OpenSSL 1.1.1. | |
110 | ||
cc99526d RL |
111 | =head1 SEE ALSO |
112 | ||
7714dc5e | 113 | L<SSL_get_error(3)>, L<SSL_read_ex(3)>, L<SSL_read(3)> |
9b86974e RS |
114 | L<SSL_CTX_set_mode(3)>, L<SSL_CTX_new(3)>, |
115 | L<SSL_connect(3)>, L<SSL_accept(3)> | |
116 | L<SSL_set_connect_state(3)>, | |
b97fdb57 | 117 | L<ssl(7)>, L<bio(7)> |
cc99526d | 118 | |
e2f92610 RS |
119 | =head1 COPYRIGHT |
120 | ||
1212818e | 121 | Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 122 | |
4746f25a | 123 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
124 | this file except in compliance with the License. You can obtain a copy |
125 | in the file LICENSE in the source distribution or at | |
126 | L<https://www.openssl.org/source/license.html>. | |
127 | ||
128 | =cut |