Hash Functions and Checksums ============================= Hash functions are one-way functions, which map data of arbitrary size to a fixed output length. Most of the hash functions in Botan are designed to be cryptographically secure, which means that it is computationally infeasible to create a collision (finding two inputs with the same hash) or preimages (given a hash output, generating an arbitrary input with the same hash). But note that not all such hash functions meet their goals, in particular MD4 and MD5 are trivially broken. However they are still included due to their wide adoption in various protocols. The class :cpp:class:`HashFunction` is defined in `botan/hash.h`. Using a hash function is typically split into three stages: initialization, update, and finalization (often referred to as a IUF interface). The initialization stage is implicit: after creating a hash function object, it is ready to process data. Then update is called one or more times. Calling update several times is equivalent to calling it once with all of the arguments concatenated. After completing a hash computation (eg using ``final``), the internal state is reset to begin hashing a new message. .. cpp:class:: HashFunction .. cpp:function:: static std::unique_ptr create(const std::string& name) Return a newly allocated hash function object, or nullptr if the name is not recognized. .. cpp:function:: static std::unique_ptr create_or_throw(const std::string& name) Like ``create`` except that it will throw an exception instead of returning nullptr. .. cpp:function:: size_t output_length() Return the size (in *bytes*) of the output of this function. .. cpp:function:: void update(const uint8_t* input, size_t length) Updates the computation with *input*. .. cpp:function:: void update(uint8_t input) Updates the computation with *input*. .. cpp:function:: void update(const std::vector& input) Updates the computation with *input*. .. cpp:function:: void update(const std::string& input) Updates the computation with *input*. .. cpp:function:: void final(uint8_t* out) 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. .. cpp:function:: secure_vector final() Similar to the other function of the same name, except it returns the result in a newly allocated vector. .. cpp:function:: secure_vector process(const uint8_t in[], size_t length) Equivalent to calling ``update`` followed by ``final``. .. cpp:function:: secure_vector process(const std::string& in) Equivalent to calling ``update`` followed by ``final``. .. cpp:function:: std::unique_ptr new_object() Return a newly allocated HashFunction object of the same type as this one. .. cpp:function:: std::unique_ptr copy_state() Return a newly allocated HashFunction object of the same type as this one, whose internal state matches the current state of this. Code Example ------------ Assume we want to calculate the SHA-256, SHA-384, and SHA-3 hash digests of the STDIN stream using the Botan library. .. literalinclude:: /../src/examples/hash.cpp :language: cpp Available Hash Functions ------------------------------ The following cryptographic hash functions are implemented. If in doubt, any of SHA-384, SHA-3, or BLAKE2b are fine choices. BLAKE2b ^^^^^^^^^ Available if ``BOTAN_HAS_BLAKE2B`` is defined. A recently designed hash function. Very fast on 64-bit processors. Can output a hash of any length between 1 and 64 bytes, this is specified by passing a value to the constructor with the desired length. Named like "Blake2b" which selects default 512-bit output, or as "Blake2b(256)" to select 256 bits of output. GOST-34.11 ^^^^^^^^^^^^^^^ .. deprecated:: 2.11 Available if ``BOTAN_HAS_GOST_34_11`` is defined. Russian national standard hash. It is old, slow, and has some weaknesses. Avoid it unless you must. .. warning:: As this hash function is no longer approved by the latest Russian standards, support for GOST 34.11 hash is deprecated and will be removed in a future major release. Keccak-1600 ^^^^^^^^^^^^^^^ Available if ``BOTAN_HAS_KECCAK`` is defined. An older (and incompatible) variant of SHA-3, but sometimes used. Prefer SHA-3 in new code. MD4 ^^^^^^^^^ An old and now broken hash function. Available if ``BOTAN_HAS_MD4`` is defined. .. warning:: MD4 collisions can be easily created. There is no safe cryptographic use for this function. .. warning:: Support for MD4 is deprecated and will be removed in a future major release. MD5 ^^^^^^^^^ An old and now broken hash function. Available if ``BOTAN_HAS_MD5`` is defined. .. warning:: MD5 collisions can be easily created. MD5 should never be used for signatures. RIPEMD-160 ^^^^^^^^^^^^^^^ Available if ``BOTAN_HAS_RIPEMD160`` is defined. A 160 bit hash function, quite old but still thought to be secure (up to the limit of 2**80 computation required for a collision which is possible with any 160 bit hash function). Somewhat deprecated these days. Prefer SHA-2 or SHA-3 in new code. SHA-1 ^^^^^^^^^^^^^^^ Available if ``BOTAN_HAS_SHA1`` is defined. Widely adopted NSA designed hash function. Use SHA-2 or SHA-3 in new code. .. warning:: SHA-1 collisions can now be created by moderately resourced attackers. It must never be used for signatures. SHA-256 ^^^^^^^^^^^^^^^ Available if ``BOTAN_HAS_SHA2_32`` is defined. Relatively fast 256 bit hash function, thought to be secure. Also includes the variant SHA-224. There is no real reason to use SHA-224. SHA-512 ^^^^^^^^^^^^^^^ Available if ``BOTAN_HAS_SHA2_64`` is defined. SHA-512 is faster than SHA-256 on 64-bit processors. Also includes the truncated variants SHA-384 and SHA-512/256, which have the advantage of avoiding message extension attacks. SHA-3 ^^^^^^^^^^^^^^^ Available if ``BOTAN_HAS_SHA3`` is defined. The new NIST standard hash. Fairly slow. Supports 224, 256, 384 or 512 bit outputs. SHA-3 is faster with smaller outputs. Use as "SHA-3(256)" or "SHA-3(512)". Plain "SHA-3" selects default 512 bit output. SHAKE (SHAKE-128, SHAKE-256) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Available if ``BOTAN_HAS_SHAKE`` is defined. These are actually XOFs (extensible output functions) based on SHA-3, which can output a value of any byte length. For example "SHAKE-128(1024)" will produce 1024 bits of output. The specified length must be a multiple of 8. SM3 ^^^^^^^^^^^^^^^ Available if ``BOTAN_HAS_SM3`` is defined. Chinese national hash function, 256 bit output. Widely used in industry there. Fast and seemingly secure, but no reason to prefer it over SHA-2 or SHA-3 unless required. Skein-512 ^^^^^^^^^^^^^^^ Available if ``BOTAN_HAS_SKEIN_512`` is defined. A contender for the NIST SHA-3 competition. Very fast on 64-bit systems. Can output a hash of any length between 1 and 64 bytes. It also accepts an optional "personalization string" which can create variants of the hash. This is useful for domain separation. To set a personalization string set the second param to any value, typically ASCII strings are used. Examples "Skein-512(256)" or "Skein-512(384,personalization_string)". Streebog (Streebog-256, Streebog-512) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Available if ``BOTAN_HAS_STREEBOG`` is defined. Newly designed Russian national hash function. Due to use of input-dependent table lookups, it is vulnerable to side channels. There is no reason to use it unless compatibility is needed. .. warning:: The Streebog Sbox has recently been revealed to have a hidden structure which interacts with its linear layer in a way which may provide a backdoor when used in certain ways. Avoid Streebog if at all possible. Whirlpool ^^^^^^^^^^^^^^^ Available if ``BOTAN_HAS_WHIRLPOOL`` is defined. A 512-bit hash function standardized by ISO and NESSIE. Relatively slow, and due to the table based implementation it is potentially vulnerable to cache based side channels. Hash Function Combiners --------------------------- These are functions which combine multiple hash functions to create a new hash function. They are typically only used in specialized applications. Parallel ^^^^^^^^^^^^^ Available if ``BOTAN_HAS_PARALLEL_HASH`` is defined. Parallel simply concatenates multiple hash functions. For example "Parallel(SHA-256,SHA-512)" outputs a 256+512 bit hash created by hashing the input with both SHA-256 and SHA-512 and concatenating the outputs. Note that due to the "multicollision attack" it turns out that generating a collision for multiple parallel hash functions is no harder than generating a collision for the strongest hash function. Comp4P ^^^^^^^^^^^^^ Available if ``BOTAN_HAS_COMB4P`` is defined. This combines two cryptographic hashes in such a way that preimage and collision attacks are provably at least as hard as a preimage or collision attack on the strongest hash. Checksums ---------------- .. note:: Checksums are not suitable for cryptographic use, but can be used for error checking purposes. Adler32 ^^^^^^^^^^^ Available if ``BOTAN_HAS_ADLER32`` is defined. The Adler32 checksum is used in the zlib format. 32 bit output. CRC24 ^^^^^^^^^^^ Available if ``BOTAN_HAS_CRC24`` is defined. This is the CRC function used in OpenPGP. 24 bit output. CRC32 ^^^^^^^^^^^ Available if ``BOTAN_HAS_CRC32`` is defined. This is the 32-bit CRC used in protocols such as Ethernet, gzip, PNG, etc.