Lossless Data Compression¶
Some lossless data compression algorithms are available in botan, currently all
via third party libraries - these include zlib (including deflate and gzip
formats), bzip2, and lzma. Support for these must be enabled at build time;
you can check for them using the macros
You should always compress before you encrypt, because encryption seeks to hide the redundancy that compression is supposed to try to find and remove.
Compression is done through the
Decompression_Algorithm classes, both defined in compression.h
Compression and decompression both work in three stages: starting a
start), continuing to process it (
update), and then
finally completing processing the stream (
Initialize the compression engine. This must be done before calling
finish. The meaning of the level parameter varies by the algorithm but generally takes a value between 1 and 9, with higher values implying typically better compression from and more memory and/or CPU time consumed by the compression process. The decompressor can always handle input from any compressor.
update(secure_vector<uint8_t> &buf, size_t offset = 0, bool flush = false)¶
- Compress the material in the in/out parameter
buf. The leading
bufare ignored and remain untouched; this can be useful for ignoring packet headers. If
flushis true, the compression state is flushed, allowing the decompressor to recover the entire message up to this point without having the see the rest of the compressed stream.
Initialize the decompression engine. This must be done before calling
finish. No level is provided here; the decompressor can accept input generated by any compression parameters.
update(secure_vector<uint8_t> &buf, size_t offset = 0)¶
Decompress the material in the in/out parameter
buf. The leading
bufare ignored and remain untouched; this can be useful for ignoring packet headers.
This function may throw if the data seems to be invalid.
The easiest way to get a compressor is via the functions
Supported values for type include zlib (raw zlib with no checksum), deflate (zlib’s deflate format), gzip, bz2, and lzma. A null pointer will be returned if the algorithm is unavailable.
To use a compression algorithm in a Pipe use the adaptor types Compression_Filter and Decompression_Filter from comp_filter.h. The constructors of both filters take a std::string argument (passed to make_compressor or make_decompressor), the compression filter also takes a level parameter. Finally both constructors have a parameter buf_sz which specifies the size of the internal buffer that will be used - inputs will be broken into blocks of this size. The default is 4096.