MySQL 8.4.3
Source Code Documentation
binlog_ostream.h
Go to the documentation of this file.
1/* Copyright (c) 2018, 2024, Oracle and/or its affiliates.
2
3 This program is free software; you can redistribute it and/or modify
4 it under the terms of the GNU General Public License, version 2.0,
5 as published by the Free Software Foundation.
6
7 This program is designed to work with certain software (including
8 but not limited to OpenSSL) that is licensed under separate terms,
9 as designated in a particular file or component or in included license
10 documentation. The authors of MySQL hereby grant you an additional
11 permission to link the program and your derivative works with the
12 separately licensed software that they have either included with
13 the program or referenced in the documentation.
14
15 This program is distributed in the hope that it will be useful,
16 but WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 GNU General Public License, version 2.0, for more details.
19
20 You should have received a copy of the GNU General Public License
21 along with this program; if not, write to the Free Software
22 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
23
24#ifndef BINLOG_OSTREAM_INCLUDED
25#define BINLOG_OSTREAM_INCLUDED
26
27#include <openssl/evp.h>
28#include "sql/basic_ostream.h"
30
31// True if binlog cache is reset.
32#ifndef NDEBUG
33extern bool binlog_cache_is_reset;
34#endif
35
36/**
37 Copy data from an input stream to an output stream.
38
39 @param[in] istream the input stream where data will be copied from
40 @param[out] ostream the output stream where data will be copied into
41 @param[out] ostream_error It will be set to true if an error happens on
42 ostream and the pointer is not null. It is valid
43 only when the function returns true.
44
45 @retval false Success
46 @retval true Error happens in either the istream or ostream.
47*/
48template <class ISTREAM, class OSTREAM>
49bool stream_copy(ISTREAM *istream, OSTREAM *ostream,
50 bool *ostream_error = nullptr) {
52 unsigned char *buffer = nullptr;
53 my_off_t length = 0;
54
55 bool ret = istream->begin(&buffer, &length);
56 while (!ret && length > 0) {
57 if (ostream->write(buffer, length)) {
58 if (ostream_error != nullptr) *ostream_error = true;
59 return true;
60 }
61
62 ret = istream->next(&buffer, &length);
63 }
64 return ret;
65}
66
67/**
68 A binlog cache implementation based on IO_CACHE.
69*/
71 public:
74 const IO_CACHE_binlog_cache_storage &) = delete;
77
78 /**
79 Opens the binlog cache. It creates a memory buffer as long as cache_size.
80 The buffer will be extended up to max_cache_size when writing data. The
81 data exceeding max_cache_size will be written into a temporary file.
82
83 @param[in] dir Where the temporary file will be created
84 @param[in] prefix Prefix of the temporary file name
85 @param[in] cache_size Size of the memory buffer.
86 @param[in] max_cache_size Maximum size of the memory buffer
87 @retval false Success
88 @retval true Error
89 */
90 bool open(const char *dir, const char *prefix, my_off_t cache_size,
91 my_off_t max_cache_size);
92 void close();
93
94 bool write(const unsigned char *buffer, my_off_t length) override;
95 bool truncate(my_off_t offset) override;
96 /* purecov: inspected */
97 /* binlog cache doesn't need seek operation. Setting true to return error */
98 bool seek(my_off_t offset [[maybe_unused]]) override { return true; }
99 /**
100 Reset status and drop all data. It looks like a cache never was used after
101 reset.
102 */
103 bool reset();
104 /**
105 Returns the file name if a temporary file is opened, otherwise nullptr is
106 returned.
107 */
108 const char *tmp_file_name() const;
109 /**
110 Returns the count of calling temporary file's write()
111 */
112 size_t disk_writes() const;
113
114 /**
115 Initializes binlog cache for reading and returns the data at the begin.
116 buffer is controlled by binlog cache implementation, so caller should
117 not release it. If the function sets *length to 0 and no error happens,
118 it has reached the end of the cache.
119
120 @param[out] buffer It points to buffer where data is read.
121 @param[out] length Length of the data in the buffer.
122 @retval false Success
123 @retval true Error
124 */
125 bool begin(unsigned char **buffer, my_off_t *length);
126 /**
127 Returns next piece of data. buffer is controlled by binlog cache
128 implementation, so caller should not release it. If the function sets
129 *length to 0 and no error happens, it has reached the end of the cache.
130
131 @param[out] buffer It points to buffer where data is read.
132 @param[out] length Length of the data in the buffer.
133 @retval false Success
134 @retval true Error
135 */
136 bool next(unsigned char **buffer, my_off_t *length);
137 my_off_t length() const;
138 bool flush() override { return false; }
139 bool sync() override { return false; }
140
141 private:
144 /**
145 Enable IO Cache temporary file encryption.
146
147 @retval false Success.
148 @retval true Error.
149 */
150 bool enable_encryption();
151 /**
152 Disable IO Cache temporary file encryption.
153 */
154 void disable_encryption();
155 /**
156 Generate a new password for the temporary file encryption.
157
158 This function is called by reset() that is called every time a transaction
159 commits to cleanup the binary log cache. The file password shall vary not
160 only per temporary file, but also per transaction being committed within a
161 single client connection.
162
163 @retval false Success.
164 @retval true Error.
165 */
167};
168
169/**
170 Byte container that provides a storage for serializing session
171 binlog events. This way of arranging the classes separates storage layer
172 and binlog layer, hides the implementation detail of low level storage.
173*/
175 public:
176 ~Binlog_cache_storage() override;
177
178 bool open(my_off_t cache_size, my_off_t max_cache_size);
179 void close();
180
181 bool write(const unsigned char *buffer, my_off_t length) override {
182 assert(m_pipeline_head != nullptr);
184 }
185 /**
186 Truncates some data at the end of the binlog cache.
187
188 @param[in] offset Where the binlog cache will be truncated to.
189 @retval false Success
190 @retval true Error
191 */
192 bool truncate(my_off_t offset) { return m_pipeline_head->truncate(offset); }
193
194 /**
195 Reset status and drop all data. It looks like a cache was never used
196 after reset.
197 */
198 bool reset() { return m_file.reset(); }
199 /**
200 Returns the count of disk writes
201 */
202 size_t disk_writes() const { return m_file.disk_writes(); }
203 /**
204 Returns the name of the temporary file.
205 */
206 const char *tmp_file_name() const { return m_file.tmp_file_name(); }
207
208 /**
209 Copy all data to a output stream. This function hides the internal
210 implementation of storage detail. So it will not disturb the callers
211 if the implementation of Binlog_cache_storage is changed. If we add
212 a pipeline stream in this class, then we need to change the implementation
213 of this function. But callers are not affected.
214
215 @param[out] ostream Where the data will be copied into
216 @param[out] ostream_error It will be set to true if an error happens on
217 ostream and the pointer is not null. It is valid
218 only when the function returns true.
219 @retval false Success
220 @retval true Error happens in either the istream or ostream.
221 */
222 bool copy_to(Basic_ostream *ostream, bool *ostream_error = nullptr) {
224 return stream_copy(&m_file, ostream, ostream_error);
225 }
226
227 /**
228 Returns data length.
229 */
230 my_off_t length() const { return m_file.length(); }
231 /**
232 Returns true if binlog cache is empty.
233 */
234 bool is_empty() const { return length() == 0; }
235
236 private:
239};
240
241/**
242 It is an Truncatable_ostream which provides encryption feature. It can be
243 setup into an stream pipeline. In the pipeline, it encrypts the data
244 from up stream and then feeds the encrypted data into down stream.
245*/
247 public:
249
250 /**
251 Initialize the context used in the encryption stream and write encryption
252 header into down stream.
253
254 @param[in] down_ostream The stream for storing encrypted data.
255
256 @retval false Success
257 @retval true Error.
258 */
259 bool open(std::unique_ptr<Truncatable_ostream> down_ostream);
260
261 /**
262 Initialize the context used in the encryption stream based on the
263 header passed as parameter. It shall be used when opening an ostream for
264 a stream that was already encrypted (the cypher password already exists).
265
266 @param[in] down_ostream the stream for storing encrypted data.
267 @param[in] header the encryption header to setup the cypher.
268
269 @retval false Success.
270 @retval true Error.
271 */
272 bool open(std::unique_ptr<Truncatable_ostream> down_ostream,
273 std::unique_ptr<Rpl_encryption_header> header);
274
275 /**
276 Re-encrypt the encrypted binary/relay log file header by replacing its
277 binlog encryption key id with the current one and its encrypted file
278 password with the new one, which is got by encrypting its file password
279 with the current binlog encryption key.
280
281 @retval false Success with an empty error message.
282 @retval true Error with an error message.
283 */
284 std::pair<bool, std::string> reencrypt();
285
286 void close();
287 bool write(const unsigned char *buffer, my_off_t length) override;
288 bool truncate(my_off_t offset) override;
289 bool seek(my_off_t offset) override;
290 bool flush() override;
291 bool sync() override;
292 /**
293 Return the encrypted file header size.
294
295 @return the encrypted file header size.
296 */
297 int get_header_size();
298
299 private:
300 std::unique_ptr<Truncatable_ostream> m_down_ostream;
301 std::unique_ptr<Rpl_encryption_header> m_header;
302 std::unique_ptr<Stream_cipher> m_encryptor;
303};
304#endif // BINLOG_OSTREAM_INCLUDED
bool stream_copy(ISTREAM *istream, OSTREAM *ostream, bool *ostream_error=nullptr)
Copy data from an input stream to an output stream.
Definition: binlog_ostream.h:49
bool binlog_cache_is_reset
Definition: binlog_ostream.cc:38
The abstract class for basic output streams which provides write operation.
Definition: basic_ostream.h:37
virtual bool write(const unsigned char *buffer, my_off_t length)=0
Write some bytes into the output stream.
Byte container that provides a storage for serializing session binlog events.
Definition: binlog_ostream.h:174
bool truncate(my_off_t offset)
Truncates some data at the end of the binlog cache.
Definition: binlog_ostream.h:192
~Binlog_cache_storage() override
Definition: binlog_ostream.cc:267
my_off_t length() const
Returns data length.
Definition: binlog_ostream.h:230
IO_CACHE_binlog_cache_storage m_file
Definition: binlog_ostream.h:238
bool is_empty() const
Returns true if binlog cache is empty.
Definition: binlog_ostream.h:234
Truncatable_ostream * m_pipeline_head
Definition: binlog_ostream.h:237
bool open(my_off_t cache_size, my_off_t max_cache_size)
Definition: binlog_ostream.cc:253
bool reset()
Reset status and drop all data.
Definition: binlog_ostream.h:198
size_t disk_writes() const
Returns the count of disk writes.
Definition: binlog_ostream.h:202
const char * tmp_file_name() const
Returns the name of the temporary file.
Definition: binlog_ostream.h:206
bool copy_to(Basic_ostream *ostream, bool *ostream_error=nullptr)
Copy all data to a output stream.
Definition: binlog_ostream.h:222
bool write(const unsigned char *buffer, my_off_t length) override
Write some bytes into the output stream.
Definition: binlog_ostream.h:181
void close()
Definition: binlog_ostream.cc:262
It is an Truncatable_ostream which provides encryption feature.
Definition: binlog_ostream.h:246
int get_header_size()
Return the encrypted file header size.
Definition: binlog_ostream.cc:411
bool open(std::unique_ptr< Truncatable_ostream > down_ostream)
Initialize the context used in the encryption stream and write encryption header into down stream.
Definition: binlog_ostream.cc:280
std::unique_ptr< Rpl_encryption_header > m_header
Definition: binlog_ostream.h:301
std::unique_ptr< Truncatable_ostream > m_down_ostream
Definition: binlog_ostream.h:300
std::unique_ptr< Stream_cipher > m_encryptor
Definition: binlog_ostream.h:302
void close()
Definition: binlog_ostream.cc:363
std::pair< bool, std::string > reencrypt()
Re-encrypt the encrypted binary/relay log file header by replacing its binlog encryption key id with ...
Definition: binlog_ostream.cc:316
bool write(const unsigned char *buffer, my_off_t length) override
Write some bytes into the output stream.
Definition: binlog_ostream.cc:369
bool sync() override
Sync.
Definition: binlog_ostream.cc:409
~Binlog_encryption_ostream() override
Definition: binlog_ostream.cc:269
bool flush() override
Flush data.
Definition: binlog_ostream.cc:407
bool truncate(my_off_t offset) override
Truncate some data at the end of the output stream.
Definition: binlog_ostream.cc:401
bool seek(my_off_t offset) override
Put the write position to a given offset.
Definition: binlog_ostream.cc:396
A binlog cache implementation based on IO_CACHE.
Definition: binlog_ostream.h:70
void disable_encryption()
Disable IO Cache temporary file encryption.
Definition: binlog_ostream.cc:223
bool seek(my_off_t offset) override
Put the write position to a given offset.
Definition: binlog_ostream.h:98
const char * tmp_file_name() const
Returns the file name if a temporary file is opened, otherwise nullptr is returned.
Definition: binlog_ostream.cc:147
my_off_t m_max_cache_size
Definition: binlog_ostream.h:143
IO_CACHE_binlog_cache_storage(const IO_CACHE_binlog_cache_storage &)=delete
bool sync() override
Sync.
Definition: binlog_ostream.h:139
bool begin(unsigned char **buffer, my_off_t *length)
Initializes binlog cache for reading and returns the data at the begin.
Definition: binlog_ostream.cc:151
IO_CACHE_binlog_cache_storage & operator=(const IO_CACHE_binlog_cache_storage &)=delete
bool flush() override
Flush data.
Definition: binlog_ostream.h:138
bool reset()
Reset status and drop all data.
Definition: binlog_ostream.cc:108
bool truncate(my_off_t offset) override
Truncate some data at the end of the output stream.
Definition: binlog_ostream.cc:93
bool setup_ciphers_password()
Generate a new password for the temporary file encryption.
Definition: binlog_ostream.cc:234
size_t disk_writes() const
Returns the count of calling temporary file's write()
Definition: binlog_ostream.cc:143
bool open(const char *dir, const char *prefix, my_off_t cache_size, my_off_t max_cache_size)
Opens the binlog cache.
Definition: binlog_ostream.cc:44
my_off_t length() const
Definition: binlog_ostream.cc:196
bool enable_encryption()
Enable IO Cache temporary file encryption.
Definition: binlog_ostream.cc:201
void close()
Definition: binlog_ostream.cc:59
IO_CACHE m_io_cache
Definition: binlog_ostream.h:142
~IO_CACHE_binlog_cache_storage() override
Definition: binlog_ostream.cc:42
bool write(const unsigned char *buffer, my_off_t length) override
Write some bytes into the output stream.
Definition: binlog_ostream.cc:61
bool next(unsigned char **buffer, my_off_t *length)
Returns next piece of data.
Definition: binlog_ostream.cc:184
Truncatable_ostream abstract class provides seek() and truncate() interfaces to all truncatable outpu...
Definition: basic_ostream.h:58
virtual bool truncate(my_off_t offset)=0
Truncate some data at the end of the output stream.
#define DBUG_TRACE
Definition: my_dbug.h:146
ulonglong my_off_t
Definition: my_inttypes.h:72
std::string dir
Double write files location.
Definition: buf0dblwr.cc:77
bool length(const dd::Spatial_reference_system *srs, const Geometry *g1, double *length, bool *null) noexcept
Computes the length of linestrings and multilinestrings.
Definition: length.cc:76
mutable_buffer buffer(void *p, size_t n) noexcept
Definition: buffer.h:418
This file includes the major components for encrypting/decrypting binary log files.
Definition: my_sys.h:346
static uint64_t cache_size
Definition: xcom_cache.cc:362