git / moonbite-core / src/crypto/blake3/README.md · raw

The official C implementation of BLAKE3.# ExampleAn example program that hashes bytes from standard input and prints theresult:```c#include "blake3.h"#include <stdio.h>#include <unistd.h>int main() {  // Initialize the hasher.  blake3_hasher hasher;  blake3_hasher_init(&hasher);  // Read input bytes from stdin.  unsigned char buf[65536];  ssize_t n;  while ((n = read(STDIN_FILENO, buf, sizeof(buf))) > 0) {    blake3_hasher_update(&hasher, buf, n);  }  // Finalize the hash. BLAKE3_OUT_LEN is the default output length, 32 bytes.  uint8_t output[BLAKE3_OUT_LEN];  blake3_hasher_finalize(&hasher, output, BLAKE3_OUT_LEN);  // Print the hash as hexadecimal.  for (size_t i = 0; i < BLAKE3_OUT_LEN; i++) {    printf("%02x", output[i]);  }  printf("\n");  return 0;}```The code above is included in this directory as `example.c`. If you'reon x86\_64 with a Unix-like OS, you can compile a working binary likethis:```bashgcc -O3 -o example example.c blake3.c blake3_dispatch.c blake3_portable.c \    blake3_sse2_x86-64_unix.S blake3_sse41_x86-64_unix.S blake3_avx2_x86-64_unix.S \    blake3_avx512_x86-64_unix.S```# API## The Struct```ctypedef struct {  // private fields} blake3_hasher;```An incremental BLAKE3 hashing state, which can accept any number ofupdates. This implementation doesn't allocate any heap memory, but`sizeof(blake3_hasher)` itself is relatively large, currently 1912 byteson x86-64. This size can be reduced by restricting the maximum inputlength, as described in Section 5.4 of [the BLAKE3spec](https://github.com/BLAKE3-team/BLAKE3-specs/blob/master/blake3.pdf),but this implementation doesn't currently support that strategy.## Common API Functions```cvoid blake3_hasher_init(  blake3_hasher *self);```Initialize a `blake3_hasher` in the default hashing mode.---```cvoid blake3_hasher_update(  blake3_hasher *self,  const void *input,  size_t input_len);```Add input to the hasher. This can be called any number of times.---```cvoid blake3_hasher_finalize(  const 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 finalizeagain after adding more input. The constant `BLAKE3_OUT_LEN` providesthe default output length, 32 bytes, which is recommended for mostcallers.Outputs shorter than the default length of 32 bytes (256 bits) provideless security. An N-bit BLAKE3 output is intended to provide N bits offirst and second preimage resistance and N/2 bits of collisionresistance, for any N up to 256. Longer outputs don't provide anyadditional security.Shorter BLAKE3 outputs are prefixes of longer ones. Explicitlyrequesting a short output is equivalent to truncating the default-lengthoutput. (Note that this is different between BLAKE2 and BLAKE3.)## Less Common API Functions```cvoid blake3_hasher_init_keyed(  blake3_hasher *self,  const uint8_t key[BLAKE3_KEY_LEN]);```Initialize a `blake3_hasher` in the keyed hashing mode. The key must beexactly 32 bytes.---```cvoid blake3_hasher_init_derive_key(  blake3_hasher *self,  const char *context);```Initialize a `blake3_hasher` in the key derivation mode. The contextstring is given as an initialization parameter, and afterwards input keymaterial should be given with `blake3_hasher_update`. The context stringis a null-terminated C string which should be **hardcoded, globallyunique, and application-specific**. The context string should notinclude any dynamic input like salts, nonces, or identifiers read from adatabase at runtime. A good default format for the context string is`"[application] [commit timestamp] [purpose]"`, e.g., `"example.com2019-12-25 16:18:03 session tokens v1"`.This function is intended for application code written in C. Forlanguage bindings, see `blake3_hasher_init_derive_key_raw` below.---```cvoid blake3_hasher_init_derive_key_raw(  blake3_hasher *self,  const void *context,  size_t context_len);```As `blake3_hasher_init_derive_key` above, except that the context stringis given as a pointer to an array of arbitrary bytes with a providedlength. This is intended for writing language bindings, where C stringconversion would add unnecessary overhead and new error cases. Unicodestrings should be encoded as UTF-8.Application code in C should prefer `blake3_hasher_init_derive_key`,which takes the context as a C string. If you need to use arbitrarybytes as a context string in application code, consider whether you'reviolating the requirement that context strings should be hardcoded.---```cvoid blake3_hasher_finalize_seek(  const blake3_hasher *self,  uint64_t seek,  uint8_t *out,  size_t out_len);```The same as `blake3_hasher_finalize`, but with an additional `seek`parameter for the starting byte position in the output stream. Toefficiently stream a large output without allocating memory, call thisfunction in a loop, incrementing `seek` by the output length each time.# BuildingThis implementation is just C and assembly files. It doesn't include apublic-facing build system. (The `Makefile` in this directory is onlyfor testing.) Instead, the intention is that you can include these filesin whatever build system you're already using. This section describesthe commands your build system should execute, or which you can executeby hand. Note that these steps may change in future versions.## x86Dynamic dispatch is enabled by default on x86. The implementation willquery the CPU at runtime to detect SIMD support, and it will use thewidest 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 oneversion using C intrinsics. The assembly versions are generallypreferred. They perform better, they perform more consistently acrossdifferent compilers, and they build more quickly. On the other hand, theassembly versions are x86\_64-only, and you need to select the rightflavor for your target platform.Here's an example of building a shared library on x86\_64 Linux usingthe assembly implementations:```bashgcc -shared -O3 -o libblake3.so blake3.c blake3_dispatch.c blake3_portable.c \    blake3_sse2_x86-64_unix.S blake3_sse41_x86-64_unix.S blake3_avx2_x86-64_unix.S \    blake3_avx512_x86-64_unix.S```When building the intrinsics-based implementations, you need to buildeach implementation separately, with the corresponding instruction setexplicitly enabled in the compiler. Here's the same shared library usingthe intrinsics-based implementations:```bashgcc -c -fPIC -O3 -msse2 blake3_sse2.c -o blake3_sse2.ogcc -c -fPIC -O3 -msse4.1 blake3_sse41.c -o blake3_sse41.ogcc -c -fPIC -O3 -mavx2 blake3_avx2.c -o blake3_avx2.ogcc -c -fPIC -O3 -mavx512f -mavx512vl blake3_avx512.c -o blake3_avx512.ogcc -shared -O3 -o libblake3.so blake3.c blake3_dispatch.c blake3_portable.c \    blake3_avx2.o blake3_avx512.o blake3_sse41.o blake3_sse2.o```Note above that building `blake3_avx512.c` requires both `-mavx512f` and`-mavx512vl` under GCC and Clang. Under MSVC, the single `/arch:AVX512`flag is sufficient. The MSVC equivalent of `-mavx2` is `/arch:AVX2`.MSVC enables SSE2 and SSE4.1 by defaut, and it doesn't have acorresponding flag.If you want to omit SIMD code entirely, you need to explicitly disableeach instruction set. Here's an example of building a shared library onx86 with only portable code:```bashgcc -shared -O3 -o libblake3.so -DBLAKE3_NO_SSE2 -DBLAKE3_NO_SSE41 -DBLAKE3_NO_AVX2 \    -DBLAKE3_NO_AVX512 blake3.c blake3_dispatch.c blake3_portable.c```## ARM NEONThe NEON implementation is not enabled by default on ARM, since not allARM targets support it. To enable it, set `BLAKE3_USE_NEON=1`. Here's anexample of building a shared library on ARM Linux with NEON support:```bashgcc -shared -O3 -o libblake3.so -DBLAKE3_USE_NEON blake3.c blake3_dispatch.c \    blake3_portable.c blake3_neon.c```Note that on some targets (ARMv7 in particular), extra flags may berequired to activate NEON support in the compiler. If you see an errorlike...```/usr/lib/gcc/armv7l-unknown-linux-gnueabihf/9.2.0/include/arm_neon.h:635:1: error: inlining failedin call to always_inline ‘vaddq_u32’: target specific option mismatch```...then you may need to add something like `-mfpu=neon-vfpv4-mfloat-abi=hard`.## Other PlatformsThe portable implementation should work on most other architectures. Forexample:```bashgcc -shared -O3 -o libblake3.so blake3.c blake3_dispatch.c blake3_portable.c```# MultithreadingUnlike the Rust implementation, the C implementation doesn't currently supportmultithreading. A future version of this library could add support by taking anoptional dependency on OpenMP or similar. Alternatively, we could expose alower-level API to allow callers to implement concurrency themselves. Theformer would be more convenient and less error-prone, but the latter would givecallers the maximum possible amount of control. The best choice here depends onthe specific use case, so if you have a use case for multithreaded hashing inC, please file a GitHub issue and let us know.