aboutsummaryrefslogtreecommitdiffstats
path: root/contrib/libs/llvm16/lib/Support/BLAKE3/README.md
blob: 319a7514e8b5025773bd8d811a801b1ffa8ab8be (plain) (blame)
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
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
Implementation of BLAKE3, originating from https://github.com/BLAKE3-team/BLAKE3/tree/1.3.1/c

# Example

An example program that hashes bytes from standard input and prints the
result:

Using the C++ API:

```c++
#include "llvm/Support/BLAKE3.h"
#include <errno.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <unistd.h>

int main() {
  // Initialize the hasher.
  llvm::BLAKE3 hasher;

  // Read input bytes from stdin.
  char buf[65536];
  while (1) {
    ssize_t n = read(STDIN_FILENO, buf, sizeof(buf));
    if (n > 0) {
      hasher.update(llvm::StringRef(buf, n));
    } else if (n == 0) {
      break; // end of file
    } else {
      fprintf(stderr, "read failed: %s\n", strerror(errno));
      exit(1);
    }
  }

  // Finalize the hash. Default output length is 32 bytes.
  auto output = hasher.final();

  // Print the hash as hexadecimal.
  for (uint8_t byte : output) {
    printf("%02x", byte);
  }
  printf("\n");
  return 0;
}
```

Using the C API:

```c
#include "llvm-c/blake3.h"
#include <errno.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <unistd.h>

int main() {
  // Initialize the hasher.
  llvm_blake3_hasher hasher;
  llvm_blake3_hasher_init(&hasher);

  // Read input bytes from stdin.
  unsigned char buf[65536];
  while (1) {
    ssize_t n = read(STDIN_FILENO, buf, sizeof(buf));
    if (n > 0) {
      llvm_blake3_hasher_update(&hasher, buf, n);
    } else if (n == 0) {
      break; // end of file
    } else {
      fprintf(stderr, "read failed: %s\n", strerror(errno));
      exit(1);
    }
  }

  // Finalize the hash. LLVM_BLAKE3_OUT_LEN is the default output length, 32 bytes.
  uint8_t output[LLVM_BLAKE3_OUT_LEN];
  llvm_blake3_hasher_finalize(&hasher, output, LLVM_BLAKE3_OUT_LEN);

  // Print the hash as hexadecimal.
  for (size_t i = 0; i < LLVM_BLAKE3_OUT_LEN; i++) {
    printf("%02x", output[i]);
  }
  printf("\n");
  return 0;
}
```

# API

## The Class/Struct

```c++
class BLAKE3 {
  // API
private:
  llvm_blake3_hasher Hasher;
};
```
```c
typedef struct {
  // private fields
} llvm_blake3_hasher;
```

An incremental BLAKE3 hashing state, which can accept any number of
updates. This implementation doesn't allocate any heap memory, but
`sizeof(llvm_blake3_hasher)` itself is relatively large, currently 1912 bytes
on x86-64. This size can be reduced by restricting the maximum input
length, as described in Section 5.4 of [the BLAKE3
spec](https://github.com/BLAKE3-team/BLAKE3-specs/blob/master/blake3.pdf),
but this implementation doesn't currently support that strategy.

## Common API Functions

```c++
BLAKE3::BLAKE3();

void BLAKE3::init();
```
```c
void llvm_blake3_hasher_init(
  llvm_blake3_hasher *self);
```

Initialize a `llvm_blake3_hasher` in the default hashing mode.

---

```c++
void BLAKE3::update(ArrayRef<uint8_t> Data);

void BLAKE3::update(StringRef Str);
```
```c
void llvm_blake3_hasher_update(
  llvm_blake3_hasher *self,
  const void *input,
  size_t input_len);
```

Add input to the hasher. This can be called any number of times.

---

```c++
template <size_t NumBytes = LLVM_BLAKE3_OUT_LEN>
using BLAKE3Result = std::array<uint8_t, NumBytes>;

template <size_t NumBytes = LLVM_BLAKE3_OUT_LEN>
void BLAKE3::final(BLAKE3Result<NumBytes> &Result);

template <size_t NumBytes = LLVM_BLAKE3_OUT_LEN>
BLAKE3Result<NumBytes> BLAKE3::final();
```
```c
void llvm_blake3_hasher_finalize(
  const llvm_blake3_hasher *self,
  uint8_t *out,
  size_t out_len);
```

Finalize the hasher and return an output of any length, given in bytes.
This doesn't modify the hasher itself, and it's possible to finalize
again after adding more input. The constant `LLVM_BLAKE3_OUT_LEN` provides
the default output length, 32 bytes, which is recommended for most
callers.

Outputs shorter than the default length of 32 bytes (256 bits) provide
less security. An N-bit BLAKE3 output is intended to provide N bits of
first and second preimage resistance and N/2 bits of collision
resistance, for any N up to 256. Longer outputs don't provide any
additional security.

Shorter BLAKE3 outputs are prefixes of longer ones. Explicitly
requesting a short output is equivalent to truncating the default-length
output. (Note that this is different between BLAKE2 and BLAKE3.)

## Less Common API Functions

```c
void llvm_blake3_hasher_init_keyed(
  llvm_blake3_hasher *self,
  const uint8_t key[LLVM_BLAKE3_KEY_LEN]);
```

Initialize a `llvm_blake3_hasher` in the keyed hashing mode. The key must be
exactly 32 bytes.

---

```c
void llvm_blake3_hasher_init_derive_key(
  llvm_blake3_hasher *self,
  const char *context);
```

Initialize a `llvm_blake3_hasher` in the key derivation mode. The context
string is given as an initialization parameter, and afterwards input key
material should be given with `llvm_blake3_hasher_update`. The context string
is a null-terminated C string which should be **hardcoded, globally
unique, and application-specific**. The context string should not
include any dynamic input like salts, nonces, or identifiers read from a
database at runtime. A good default format for the context string is
`"[application] [commit timestamp] [purpose]"`, e.g., `"example.com
2019-12-25 16:18:03 session tokens v1"`.

This function is intended for application code written in C. For
language bindings, see `llvm_blake3_hasher_init_derive_key_raw` below.

---

```c
void llvm_blake3_hasher_init_derive_key_raw(
  llvm_blake3_hasher *self,
  const void *context,
  size_t context_len);
```

As `llvm_blake3_hasher_init_derive_key` above, except that the context string
is given as a pointer to an array of arbitrary bytes with a provided
length. This is intended for writing language bindings, where C string
conversion would add unnecessary overhead and new error cases. Unicode
strings should be encoded as UTF-8.

Application code in C should prefer `llvm_blake3_hasher_init_derive_key`,
which takes the context as a C string. If you need to use arbitrary
bytes as a context string in application code, consider whether you're
violating the requirement that context strings should be hardcoded.

---

```c
void llvm_blake3_hasher_finalize_seek(
  const llvm_blake3_hasher *self,
  uint64_t seek,
  uint8_t *out,
  size_t out_len);
```

The same as `llvm_blake3_hasher_finalize`, but with an additional `seek`
parameter for the starting byte position in the output stream. To
efficiently stream a large output without allocating memory, call this
function in a loop, incrementing `seek` by the output length each time.

---

```c
void llvm_blake3_hasher_reset(
  llvm_blake3_hasher *self);
```

Reset the hasher to its initial state, prior to any calls to
`llvm_blake3_hasher_update`. Currently this is no different from calling
`llvm_blake3_hasher_init` or similar again. However, if this implementation gains
multithreading support in the future, and if `llvm_blake3_hasher` holds (optional)
threading resources, this function will reuse those resources.


# Building

This implementation is just C and assembly files.

## x86

Dynamic dispatch is enabled by default on x86. The implementation will
query the CPU at runtime to detect SIMD support, and it will use the
widest instruction set available. By default, `blake3_dispatch.c`
expects to be linked with code for five different instruction sets:
portable C, SSE2, SSE4.1, AVX2, and AVX-512.

For each of the x86 SIMD instruction sets, four versions are available:
three flavors of assembly (Unix, Windows MSVC, and Windows GNU) and one
version using C intrinsics. The assembly versions are generally
preferred. They perform better, they perform more consistently across
different compilers, and they build more quickly. On the other hand, the
assembly versions are x86\_64-only, and you need to select the right
flavor for your target platform.

## ARM NEON

The NEON implementation is enabled by default on AArch64, but not on
other ARM targets, since not all of them support it. To enable it, set
`BLAKE3_USE_NEON=1`.

To explicitiy disable using NEON instructions on AArch64, set
`BLAKE3_USE_NEON=0`.

## Other Platforms

The portable implementation should work on most other architectures.

# Multithreading

The implementation doesn't currently support multithreading.