1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
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.
|
