diff options
Diffstat (limited to 'comm/third_party/botan/doc/api_ref/compression.rst')
| -rw-r--r-- | comm/third_party/botan/doc/api_ref/compression.rst | 90 |
1 files changed, 90 insertions, 0 deletions
diff --git a/comm/third_party/botan/doc/api_ref/compression.rst b/comm/third_party/botan/doc/api_ref/compression.rst new file mode 100644 index 0000000000..5637a5a682 --- /dev/null +++ b/comm/third_party/botan/doc/api_ref/compression.rst @@ -0,0 +1,90 @@ +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 ``BOTAN_HAS_ZLIB``, ``BOTAN_HAS_BZIP2``, +and ``BOTAN_HAS_LZMA``. + +.. note:: + 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 ``Compression_Algorithm`` and +``Decompression_Algorithm`` classes, both defined in `compression.h` + +Compression and decompression both work in three stages: starting a +message (``start``), continuing to process it (``update``), and then +finally completing processing the stream (``finish``). + +.. cpp:class:: Compression_Algorithm + + .. cpp:function:: void start(size_t level) + + Initialize the compression engine. This must be done before calling + ``update`` or ``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. + + .. cpp:function:: void update(secure_vector<uint8_t>& buf, \ + size_t offset = 0, bool flush = false) + + Compress the material in the in/out parameter ``buf``. The leading + ``offset`` bytes of ``buf`` are ignored and remain untouched; this can be + useful for ignoring packet headers. If ``flush`` is 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. + + .. cpp::function:: void finish(secure_vector<uint8_t>& buf, size_t offset = 0) + + Finish compressing a message. The ``buf`` and ``offset`` parameters are + treated as in ``update``. It is acceptable to call ``start`` followed by + ``finish`` with the entire message, without any intervening call to + ``update``. + +.. cpp:class:: Decompression_Algorithm + + .. cpp:function:: void start() + + Initialize the decompression engine. This must be done before calling + ``update`` or ``finish``. No level is provided here; the decompressor + can accept input generated by any compression parameters. + + .. cpp:function:: void update(secure_vector<uint8_t>& buf, \ + size_t offset = 0) + + Decompress the material in the in/out parameter ``buf``. The leading + ``offset`` bytes of ``buf`` are ignored and remain untouched; this can be + useful for ignoring packet headers. + + This function may throw if the data seems to be invalid. + + .. cpp::function:: void finish(secure_vector<uint8_t>& buf, size_t offset = 0) + + Finish decompressing a message. The ``buf`` and ``offset`` parameters are + treated as in ``update``. It is acceptable to call ``start`` followed by + ``finish`` with the entire message, without any intervening call to + ``update``. + + This function may throw if the data seems to be invalid. + +The easiest way to get a compressor is via the functions + +.. cpp:function:: Compression_Algorithm* make_compressor(std::string type) +.. cpp:function:: Decompression_Algorithm* make_decompressor(std::string type) + +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 adapter 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. |