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