diff options
Diffstat (limited to 'doc/manual/hash.rst')
| -rw-r--r-- | doc/manual/hash.rst | 121 |
1 files changed, 121 insertions, 0 deletions
diff --git a/doc/manual/hash.rst b/doc/manual/hash.rst new file mode 100644 index 000000000..12266207d --- /dev/null +++ b/doc/manual/hash.rst @@ -0,0 +1,121 @@ +Hash Functions and Checksums +============================= +Hash functions are one-way functions, which map data of arbitrary size +to a fixed output length. The class :cpp:class:`HashFunction` is derived from +the base class :cpp:class:`BufferedComputation` and defined in `botan/hash.h`. +A Botan :cpp:class:`BufferedComputation` is split into three stages: + +1. Instantiation. +2. Data processing. +3. Finalization. + +.. cpp:class:: BufferedComputation + + .. cpp:function:: size_t output_length() + + Return the size of the output of this function. + + .. cpp:function:: void update(const byte* input, size_t length) + + .. cpp:function:: void update(byte input) + + .. cpp:function:: void update(const std::string& input) + + Updates the computation with *input*. + + .. cpp:function:: void final(byte* out) + + .. cpp:function:: secure_vector<byte> final() + + Finalize the calculation and place the result into ``out``. + For the argument taking an array, exactly ``output_length`` bytes will + be written. After you call ``final``, the algorithm is reset to + its initial state, so it may be reused immediately. + + The second method of using final is to call it with no arguments at + all, as shown in the second prototype. It will return the result + value in a memory buffer. + + There is also a pair of functions called ``process``. They are a + combination of a single ``update``, and ``final``. Both versions + return the final value, rather than placing it an array. Calling + ``process`` with a single byte value isn't available, mostly because + it would rarely be useful. + +Botan implements the following hash algorithms: + +1. Checksums: + - Adler32 + - CRC24 + - CRC32 +#. Cryptographic hash functions: + - BLAKE2 + - GOST-34.11 + - Keccak-1600 + - MD4 + - MD5 + - RIPEMD-160 + - SHA-1 + - SHA-2 (SHA-224, SHA-256, SHA-384, SHA-512-256) + - SHA-3 + - SHAKE (SHAKE-128, SHAKE-256) + - Skein-512 + - Tiger + - Whirlpool + +.. note:: Checksums are not suitable for cryptographic use, but can be used for error checking purposes. + +CLI +--- +The Botan command line interface allows the user to compute hash digests of files or datastreams. ``botan hash --algo=SHA-256 --buf-size=4096 *files`` can be used to invoke a hash computation. + +CLI Example +^^^^^^^^^^^^^ +.. code-block:: sh + + $ echo -n randombit | botan hash --algo=SHA-3 + 783A78B369AA0DE71A6155180EA9D544E7A1834CC4951548C3CE7D5E012C8C6B7EAE1C27DBDFA4DA58EE7B79B5CF07E7E6691AE39BEC1A7DDC501249266BB050`` + +Code Example +------------ +Assume we want to calculate the SHA-1, Whirlpool and SHA-3 hash digests of the STDIN stream using the Botan library. + +.. code-block:: cpp + + #include <botan/hash.h> + #include <botan/hex.h> + #include <iostream> + int main () + { + std::unique_ptr<Botan::HashFunction> hash1(Botan::HashFunction::create("SHA-1")); + std::unique_ptr<Botan::HashFunction> hash2(Botan::HashFunction::create("Whirlpool")); + std::unique_ptr<Botan::HashFunction> hash3(Botan::HashFunction::create("SHA-3")); + std::vector<uint8_t> buf(2048); + + while(std::cin.good()) + { + //read STDIN to buffer + std::cin.read(reinterpret_cast<char*>(buf.data()), buf.size()); + size_t readcount = std::cin.gcount(); + //update hash computations with read data + hash1->update(buf.data(),readcount); + hash2->update(buf.data(),readcount); + hash3->update(buf.data(),readcount); + } + std::cout << "SHA-1: " << Botan::hex_encode(hash1->final()) << std::endl; + std::cout << "Whirlpool: " << Botan::hex_encode(hash2->final()) << std::endl; + std::cout << "SHA-3: " << Botan::hex_encode(hash3->final()) << std::endl; + return 0; + } + + +A Note on Checksums +-------------------- + +Checksums are very similar to hash functions, and in fact share the +same interface. But there are some significant differences, the major +ones being that the output size is very small (usually in the range of +2 to 4 bytes), and is not cryptographically secure. But for their +intended purpose (error checking), they perform very well. Some +examples of checksums included in Botan are the Adler32 and CRC32 +checksums.
\ No newline at end of file |