Botan 3.8.1
Crypto and TLS for C&
compression.h
Go to the documentation of this file.
1/*
2* Compression Transform
3* (C) 2014 Jack Lloyd
4*
5* Botan is released under the Simplified BSD License (see license.txt)
6*/
7
8#ifndef BOTAN_COMPRESSION_TRANSFORM_H_
9#define BOTAN_COMPRESSION_TRANSFORM_H_
10
11#include <botan/exceptn.h>
12#include <botan/secmem.h>
13#include <memory>
14#include <string>
15
16namespace Botan {
17
18/**
19* Interface for a compression algorithm.
20*/
22 public:
23 /**
24 * Create an instance based on a name, or return null if the
25 * algo combination cannot be found.
26 */
27 static std::unique_ptr<Compression_Algorithm> create(std::string_view algo_spec);
28
29 /**
30 * Create an instance based on a name
31 * @param algo_spec algorithm name
32 * Throws Lookup_Error if not found.
33 */
34 static std::unique_ptr<Compression_Algorithm> create_or_throw(std::string_view algo_spec);
35
36 /**
37 * Begin compressing. Most compression algorithms offer a tunable
38 * time/compression tradeoff parameter generally represented by an integer
39 * in the range of 1 to 9. Higher values typically imply better compression
40 * and more memory and/or CPU time consumed by the compression process.
41 *
42 * If 0 or a value out of range is provided, a compression algorithm
43 * specific default is used.
44 *
45 * @param comp_level the desired level of compression (typically from 1 to 9)
46 */
47 virtual void start(size_t comp_level = 0) = 0;
48
49 /**
50 * Process some data.
51 *
52 * The leading @p offset bytes of @p buf are ignored and remain untouched;
53 * this can be useful for ignoring packet headers. If @p flush is true,
54 * the compression state is flushed, allowing the decompressor to recover
55 * the entire message up to this point without having to see the rest of
56 * the compressed stream.
57 *
58 * @param buf in/out parameter which will possibly be resized or swapped
59 * @param offset an offset into blocks to begin processing
60 * @param flush if true the compressor will be told to flush state
61 */
62 virtual void update(secure_vector<uint8_t>& buf, size_t offset = 0, bool flush = false) = 0;
63
64 /**
65 * Finish compressing
66 *
67 * The @p buf and @p offset parameters are treated as in update(). It is
68 * acceptable to call start() followed by finish() with the entire message,
69 * without any intervening call to update().
70 *
71 * @param final_block in/out parameter
72 * @param offset an offset into final_block to begin processing
73 */
74 virtual void finish(secure_vector<uint8_t>& final_block, size_t offset = 0) = 0;
75
76 /**
77 * @return name of the compression algorithm
78 */
79 virtual std::string name() const = 0;
80
81 /**
82 * Reset the state and abort the current message; start can be
83 * called again to process a new message.
84 */
85 virtual void clear() = 0;
86
87 virtual ~Compression_Algorithm() = default;
88};
89
90/*
91* Interface for a decompression algorithm.
92*/
94 public:
95 /**
96 * Create an instance based on a name, or return null if the
97 * algo combination cannot be found.
98 */
99 static std::unique_ptr<Decompression_Algorithm> create(std::string_view algo_spec);
100
101 /**
102 * Create an instance based on a name
103 * @param algo_spec algorithm name
104 * Throws Lookup_Error if not found.
105 */
106 static std::unique_ptr<Decompression_Algorithm> create_or_throw(std::string_view algo_spec);
107
108 /**
109 * Begin decompressing.
110 *
111 * This initializes the decompression engine and must be done before
112 * calling update() or finish(). No level is provided here; the
113 * decompressor can accept input generated by any compression parameters.
114 */
115 virtual void start() = 0;
116
117 /**
118 * Process some data.
119 * @param buf in/out parameter which will possibly be resized or swapped
120 * @param offset an offset into blocks to begin processing
121 */
122 virtual void update(secure_vector<uint8_t>& buf, size_t offset = 0) = 0;
123
124 /**
125 * Finish decompressing
126 *
127 * Decompress the material in the in/out parameter @p buf. The leading
128 * @p offset bytes of @p buf are ignored and remain untouched; this can
129 * be useful for ignoring packet headers.
130 *
131 * This function may throw if the data seems to be invalid.
132 *
133 * @param final_block in/out parameter
134 * @param offset an offset into final_block to begin processing
135 */
136 virtual void finish(secure_vector<uint8_t>& final_block, size_t offset = 0) = 0;
137
138 /**
139 * @return name of the decompression algorithm
140 */
141 virtual std::string name() const = 0;
142
143 /**
144 * Reset the state and abort the current message; start can be
145 * called again to process a new message.
146 */
147 virtual void clear() = 0;
148
149 virtual ~Decompression_Algorithm() = default;
150};
151
152BOTAN_DEPRECATED("Use Compression_Algorithm::create")
153
154inline Compression_Algorithm* make_compressor(std::string_view type) {
155 return Compression_Algorithm::create(type).release();
156}
157
158BOTAN_DEPRECATED("Use Decompression_Algorithm::create")
159
160inline Decompression_Algorithm* make_decompressor(std::string_view type) {
161 return Decompression_Algorithm::create(type).release();
162}
163
164/**
165* An error that occurred during compression (or decompression)
166*/
167class BOTAN_PUBLIC_API(2, 9) Compression_Error final : public Exception {
168 public:
169 /**
170 * @param func_name the name of the compression API that was called
171 * (eg "BZ2_bzCompressInit" or "lzma_code")
172 * @param type what library this came from
173 * @param rc the error return code from the compression API. The
174 * interpretation of this value will depend on the library.
175 */
176 Compression_Error(const char* func_name, ErrorType type, int rc);
177
178 ErrorType error_type() const noexcept override { return m_type; }
179
180 int error_code() const noexcept override { return m_rc; }
181
182 private:
183 ErrorType m_type;
184 int m_rc;
185};
186
187/**
188* Adapts a zlib style API
189*/
191 public:
192 virtual ~Compression_Stream() = default;
193
194 virtual void next_in(uint8_t* b, size_t len) = 0;
195
196 virtual void next_out(uint8_t* b, size_t len) = 0;
197
198 virtual size_t avail_in() const = 0;
199
200 virtual size_t avail_out() const = 0;
201
202 virtual uint32_t run_flag() const = 0;
203 virtual uint32_t flush_flag() const = 0;
204 virtual uint32_t finish_flag() const = 0;
205
206 virtual bool run(uint32_t flags) = 0;
207};
208
209/**
210* Used to implement compression using Compression_Stream
211*/
213 public:
214 void update(secure_vector<uint8_t>& buf, size_t offset, bool flush) final;
215
216 void finish(secure_vector<uint8_t>& buf, size_t offset) final;
217
218 void clear() final;
219
220 private:
221 void start(size_t level) final;
222
223 void process(secure_vector<uint8_t>& buf, size_t offset, uint32_t flags);
224
225 virtual std::unique_ptr<Compression_Stream> make_stream(size_t level) const = 0;
226
227 secure_vector<uint8_t> m_buffer;
228 std::unique_ptr<Compression_Stream> m_stream;
229};
230
231/**
232* FIXME add doc
233*/
235 public:
236 void update(secure_vector<uint8_t>& buf, size_t offset) final;
237
238 void finish(secure_vector<uint8_t>& buf, size_t offset) final;
239
240 void clear() final;
241
242 private:
243 void start() final;
244
245 void process(secure_vector<uint8_t>& buf, size_t offset, uint32_t flags);
246
247 virtual std::unique_ptr<Compression_Stream> make_stream() const = 0;
248
249 secure_vector<uint8_t> m_buffer;
250 std::unique_ptr<Compression_Stream> m_stream;
251};
252
253} // namespace Botan
254
255#endif
#define BOTAN_PUBLIC_API(maj, min)
Definition api.h:19
#define BOTAN_DEPRECATED(msg)
Definition api.h:59
virtual void start(size_t comp_level=0)=0
virtual void finish(secure_vector< uint8_t > &final_block, size_t offset=0)=0
static std::unique_ptr< Compression_Algorithm > create_or_throw(std::string_view algo_spec)
static std::unique_ptr< Compression_Algorithm > create(std::string_view algo_spec)
virtual void update(secure_vector< uint8_t > &buf, size_t offset=0, bool flush=false)=0
virtual std::string name() const =0
virtual ~Compression_Algorithm()=default
ErrorType error_type() const noexcept override
int error_code() const noexcept override
Compression_Error(const char *func_name, ErrorType type, int rc)
virtual void next_in(uint8_t *b, size_t len)=0
virtual size_t avail_in() const =0
virtual ~Compression_Stream()=default
virtual uint32_t finish_flag() const =0
virtual size_t avail_out() const =0
virtual uint32_t run_flag() const =0
virtual bool run(uint32_t flags)=0
virtual void next_out(uint8_t *b, size_t len)=0
virtual uint32_t flush_flag() const =0
static std::unique_ptr< Decompression_Algorithm > create(std::string_view algo_spec)
virtual ~Decompression_Algorithm()=default
virtual std::string name() const =0
virtual void finish(secure_vector< uint8_t > &final_block, size_t offset=0)=0
static std::unique_ptr< Decompression_Algorithm > create_or_throw(std::string_view algo_spec)
virtual void update(secure_vector< uint8_t > &buf, size_t offset=0)=0
Exception(std::string_view msg)
Definition exceptn.cpp:71
void update(secure_vector< uint8_t > &buf, size_t offset, bool flush) final
void finish(secure_vector< uint8_t > &buf, size_t offset) final
void update(secure_vector< uint8_t > &buf, size_t offset) final
void finish(secure_vector< uint8_t > &buf, size_t offset) final
Decompression_Algorithm * make_decompressor(std::string_view type)
Compression_Algorithm * make_compressor(std::string_view type)
ErrorType
Definition exceptn.h:20
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:65