63 lines
2.5 KiB
ReStructuredText
63 lines
2.5 KiB
ReStructuredText
|
ZFEC Forward Error Correction
|
||
|
|
===============================
|
||
|
|
|
||
|
|
.. versionadded:: 3.0.0
|
||
|
|
|
||
|
|
The ``ZFEC`` class provides forward error correction compatible
|
||
|
|
with the `zfec <https://github.com/tahoe-lafs/zfec>`_ library.
|
||
|
|
|
||
|
|
Forward error correction takes an input and creates multiple "shares",
|
||
|
|
such that any ``K`` of ``N`` shares is sufficient to recover the
|
||
|
|
entire original input.
|
||
|
|
|
||
|
|
.. note::
|
||
|
|
Specific to the ZFEC format, the first ``K`` generated shares are
|
||
|
|
identical to the original input data, followed by ``N-K`` shares of
|
||
|
|
error correcting code. This is very different from threshold secret
|
||
|
|
sharing, where having fewer than ``K`` shares gives no information
|
||
|
|
about the original input.
|
||
|
|
|
||
|
|
.. warning::
|
||
|
|
If a corrupted share is provided to the decoding algorithm, the
|
||
|
|
resulting decoding will be invalid. It is recommended to protect
|
||
|
|
shares using a technique such as a MAC or public key signature, if
|
||
|
|
corruption is likely in your application.
|
||
|
|
|
||
|
|
``ZFEC`` requires that the input length be exactly divisible by ``K``;
|
||
|
|
if needed define a padding scheme to pad your input to the necessary
|
||
|
|
size.
|
||
|
|
|
||
|
|
An example application that adds padding and a hash checksum is available
|
||
|
|
in ``src/cli/zfec.cpp`` and invokable using ``botan fec_encode`` and
|
||
|
|
``botan fec_decode``.
|
||
|
|
|
||
|
|
.. cpp:class:: ZFEC
|
||
|
|
|
||
|
|
.. cpp:function:: ZFEC(size_t k, size_t n)
|
||
|
|
|
||
|
|
Set up for encoding or decoding using parameters ``k`` and ``n``.
|
||
|
|
Both must be less than 256, and ``k`` must be less than ``n``.
|
||
|
|
|
||
|
|
.. cpp:function:: void encode_shares(const std::vector<const uint8_t*>& shares, \
|
||
|
|
size_t share_size, \
|
||
|
|
std::function<void (size_t, const uint8_t[], size_t)> output_cb) const
|
||
|
|
|
||
|
|
Encode ``K`` shares in ``shares`` each of length ``share_size`` into ``N``
|
||
|
|
shares, also each of length ``share_size``. The ``output_cb`` function will
|
||
|
|
be called once for each output share (in some unspecified and possibly
|
||
|
|
non-deterministic order).
|
||
|
|
|
||
|
|
The parameters to ``output_cb`` are: the share being output, the share
|
||
|
|
contents, and the length of the encoded share (which will always be
|
||
|
|
equal to ``share_size``).
|
||
|
|
|
||
|
|
.. cpp:function:: void decode_shares(const std::map<size_t, const uint8_t*>& shares, \
|
||
|
|
size_t share_size, \
|
||
|
|
std::function<void (size_t, const uint8_t[], size_t)> output_cb) const
|
||
|
|
|
||
|
|
Decode some set of shares into the original input. Each share is
|
||
|
|
of ``share_size`` bytes. The shares are identified by a small
|
||
|
|
integer (between 0 and 255).
|
||
|
|
|
||
|
|
The parameters to ``output_cb`` are similar to that of ``encode_shares``.
|