Packages
macula
4.4.5
7.1.0
7.0.0
6.0.0
5.2.2
5.2.1
5.2.0
5.1.0
5.0.0
4.8.0
4.7.1
4.7.0
4.6.0
4.5.0
4.4.10
4.4.9
4.4.8
4.4.7
4.4.6
4.4.5
4.4.4
4.4.3
4.4.2
4.4.1
4.4.0
4.3.1
4.3.0
4.2.9
4.2.8
4.2.7
4.2.6
4.2.5
4.2.4
4.2.3
4.2.2
4.2.1
4.2.0
4.1.1
4.1.0
4.0.0
3.16.0
3.15.3
3.15.2
3.15.1
3.14.0
3.13.0
3.12.1
3.12.0
3.11.1
3.11.0
3.10.3
3.10.2
3.10.1
3.9.0
3.8.0
3.7.0
3.5.0
3.4.0
3.3.0
3.2.0
3.1.0
3.0.0
2.1.1
2.1.0
2.0.0
1.5.2
1.5.1
1.4.30
1.4.29
1.4.28
1.4.27
1.4.26
1.4.25
1.4.24
1.4.23
1.4.22
1.4.21
1.4.20
1.4.19
1.4.18
1.4.17
1.4.16
1.4.15
1.4.14
1.4.13
1.4.11
1.4.10
1.4.9
1.4.8
1.4.7
1.4.6
1.4.5
1.4.4
1.4.3
1.4.2
1.4.1
1.4.0
1.3.1
1.3.0
1.2.0
1.1.0
1.0.10
1.0.9
1.0.8
1.0.7
1.0.6
1.0.5
1.0.4
1.0.3
1.0.2
1.0.1
1.0.0
0.48.6
0.48.5
0.48.4
0.48.3
0.48.2
0.48.1
0.48.0
0.47.1
0.47.0
0.46.3
0.46.1
0.46.0
0.45.3
0.45.2
0.45.1
0.45.0
0.44.2
0.44.1
0.44.0
0.43.3
0.43.2
0.43.1
0.43.0
0.42.9
0.42.8
0.42.7
0.42.6
0.42.5
0.42.4
0.42.3
0.42.2
0.42.1
0.42.0
0.41.1
0.41.0
0.40.1
0.40.0
0.39.9
0.39.8
0.39.7
0.39.6
0.39.5
0.39.4
0.39.3
0.39.2
0.39.1
0.39.0
0.38.8
0.38.7
0.38.6
0.38.5
0.38.4
0.38.3
0.38.2
0.38.1
0.38.0
0.37.7
0.37.6
0.37.5
0.37.4
0.37.3
0.37.2
0.37.1
0.37.0
0.36.6
0.36.5
0.36.4
0.36.3
0.36.2
0.36.1
0.36.0
0.35.4
0.35.3
0.35.2
0.35.1
0.35.0
0.34.1
0.34.0
0.33.1
0.33.0
0.32.5
0.32.4
0.32.3
0.32.2
0.32.1
0.32.0
0.31.9
0.31.8
0.31.7
0.31.6
0.31.5
0.31.4
0.31.3
0.31.2
0.31.1
0.31.0
0.30.10
0.30.9
0.30.8
0.30.7
0.30.6
0.30.5
0.30.4
0.30.3
0.30.2
0.30.1
0.30.0
0.29.0
0.28.3
0.28.2
0.28.1
0.28.0
0.27.1
0.27.0
0.26.1
0.26.0
0.25.6
0.25.5
0.25.4
0.25.3
0.25.2
0.25.1
0.25.0
0.24.6
0.24.5
0.24.4
0.24.3
0.24.2
0.24.1
0.24.0
0.23.3
0.23.2
0.23.1
0.23.0
0.22.12
0.22.11
0.22.10
0.22.9
0.22.8
0.22.7
0.22.6
0.22.5
0.22.4
0.22.3
0.22.2
0.22.1
0.22.0
0.21.7
0.21.6
0.21.5
0.21.4
0.21.2
0.21.1
0.21.0
0.20.25
0.20.24
0.20.23
0.20.22
0.20.21
0.20.20
0.20.19
0.20.18
0.20.17
0.20.16
0.20.15
0.20.14
0.20.13
0.20.12
0.20.11
0.20.10
0.20.9
0.20.8
0.20.7
0.20.6
0.20.5
0.20.3
0.20.2
0.20.1
0.20.0
0.19.2
0.19.1
0.19.0
0.18.1
0.18.0
0.17.4
0.17.3
0.17.2
0.17.1
0.17.0
0.16.6
0.16.5
0.16.4
0.16.3
0.16.2
0.16.1
0.16.0
0.15.1
0.15.0
0.14.3
0.14.2
0.14.1
0.14.0
0.12.6
0.12.5
0.12.3
0.11.3
0.10.2
0.10.1
0.10.0
0.9.2
0.9.1
0.9.0
0.8.25
0.8.24
0.8.23
0.8.22
0.8.21
0.8.20
0.8.19
0.8.18
0.8.17
0.8.16
0.8.15
0.8.14
0.8.13
0.8.12
0.8.11
0.8.10
0.8.9
0.8.8
0.8.7
0.8.6
0.8.5
0.8.4
0.8.3
0.8.2
0.8.1
0.8.0
0.7.30
0.7.29
0.7.28
0.7.27
0.7.26
0.7.25
0.7.24
0.7.23
0.7.22
0.7.21
0.7.20
0.7.19
0.7.18
0.7.17
0.7.16
0.7.15
0.7.14
0.7.13
0.7.12
0.7.11
0.7.10
0.7.9
0.7.8
0.7.7
0.7.6
0.7.5
0.7.4
0.7.3
0.7.2
0.7.1
0.7.0
0.6.7
0.6.6
0.6.5
0.6.4
0.6.3
0.6.2
0.6.1
0.6.0
0.5.0
0.4.4
0.4.3
0.4.2
0.4.1
0.4.0
0.3.4
0.3.3
0.3.2
0.3.1
Macula HTTP/3 Mesh SDK — connect, subscribe, publish, call, advertise
Current section
Files
Jump to
Current section
Files
src/record/macula_blake3_nif.erl
%%%-------------------------------------------------------------------
%%% @doc BLAKE3 hashing with NIF acceleration and Erlang fallback.
%%%
%%% This module provides BLAKE3 cryptographic hashing with automatic
%%% fallback to a pure Erlang implementation when NIFs are not available.
%%%
%%% BLAKE3 is the primary hash algorithm for Macula content-addressed
%%% storage due to its speed (faster than SHA-256) and security.
%%%
%%% == Performance ==
%%%
%%% The NIF implementation (via Rust blake3 crate) is approximately
%%% 10-20x faster than the pure Erlang fallback, especially for
%%% large inputs.
%%%
%%% == Usage ==
%%%
%%% ```
%%% %% Hash binary data
%%% Hash = macula_blake3_nif:hash(Data).
%%%
%%% %% Hash multiple chunks (streaming)
%%% Hash = macula_blake3_nif:hash_streaming([Chunk1, Chunk2, Chunk3]).
%%%
%%% %% Verify a hash
%%% true = macula_blake3_nif:verify(Data, ExpectedHash).
%%%
%%% %% Get hex-encoded hash
%%% HexHash = macula_blake3_nif:hash_hex(Data).
%%% '''
%%% @end
%%%-------------------------------------------------------------------
-module(macula_blake3_nif).
%% API
-export([
hash/1,
hash_streaming/1,
verify/2,
hash_hex/1,
is_nif_loaded/0
]).
%% Note: NIF functions are in macula_crypto_nif module.
%% This module provides the high-level API with fallback.
-on_load(init/0).
-define(NIF_LOADED_KEY, macula_crypto_nif_loaded).
%%%===================================================================
%%% API Functions
%%%===================================================================
%% @doc Hash binary data using BLAKE3.
%% Returns a 32-byte hash.
-spec hash(binary()) -> binary().
hash(Data) when is_binary(Data) ->
case ensure_crypto_nif_loaded() of
true -> macula_crypto_nif:nif_blake3(Data);
false -> erlang_blake3(Data)
end.
%% @doc Hash multiple chunks using BLAKE3.
%% Streaming hash - processes chunks without concatenating them.
-spec hash_streaming([binary()]) -> binary().
hash_streaming(Chunks) when is_list(Chunks) ->
case ensure_crypto_nif_loaded() of
true -> macula_crypto_nif:nif_blake3_streaming(Chunks);
false -> erlang_blake3_streaming(Chunks)
end.
%% @doc Verify that data matches an expected BLAKE3 hash.
-spec verify(binary(), binary()) -> boolean().
verify(Data, ExpectedHash) when is_binary(Data), is_binary(ExpectedHash) ->
case ensure_crypto_nif_loaded() of
true -> macula_crypto_nif:nif_blake3_verify(Data, ExpectedHash);
false -> erlang_blake3(Data) =:= ExpectedHash
end.
%% @doc Hash binary data and return hex-encoded string.
-spec hash_hex(binary()) -> binary().
hash_hex(Data) when is_binary(Data) ->
case ensure_crypto_nif_loaded() of
true -> macula_crypto_nif:nif_blake3_hex(Data);
false -> hex_encode(erlang_blake3(Data))
end.
%% @doc Check if NIF is loaded. Note: returns the LAST observed
%% state — a `false' here may mean the NIF hasn't been triggered to
%% load yet (its `-on_load' fires only on first module reference).
%% Callers that NEED the NIF status to be definitive should use
%% `ensure_crypto_nif_loaded/0' which forces module-load first.
-spec is_nif_loaded() -> boolean().
is_nif_loaded() ->
persistent_term:get(?NIF_LOADED_KEY, false).
%% @private Force `macula_crypto_nif' to be code-loaded, which
%% triggers its `-on_load' callback, which writes the
%% `macula_crypto_nif_loaded' persistent_term flag if the .so
%% loaded successfully.
%%
%% Pre-fix: `macula_blake3_nif:hash/1' read the flag without first
%% ensuring the crypto-NIF module had been loaded. If no other path
%% had referenced `macula_crypto_nif' yet (e.g. an SDK consumer that
%% only ever calls `macula:put_content' / `get_content' on the way to
%% computing an MCID), `is_nif_loaded()' returned `false' and the
%% Erlang fallback fired. The fallback is NOT plain `crypto:hash(sha256, _)':
%% inputs over 1024 bytes go through a tree-hash that compresses
%% 1024-byte chunks individually with SHA-256, then pair-hashes the
%% chunk hashes — producing an output that matches NEITHER real
%% BLAKE3 (the relay's path) NOR plain SHA-256 (the relay's
%% `match_any_hash' fallback). Result: any blob > 1024 bytes hit a
%% spurious `hash_mismatch' on `_content.put_block'.
%%
%% Force-loading here makes the NIF status deterministic for every
%% caller, regardless of module-reference order. If the NIF really
%% can't load (e.g. .so missing), `code:ensure_loaded/1' still
%% succeeds (it loaded the BEAM), `-on_load' raises, the BEAM is
%% removed from the load table, and `is_nif_loaded()' returns false
%% — at which point the Erlang fallback runs. That fallback is still
%% buggy but the situation is genuinely unrecoverable; the calling
%% layer's hash will mismatch any peer that has the real NIF, and
%% surfacing that as `hash_mismatch' is correct behaviour.
ensure_crypto_nif_loaded() ->
_ = code:ensure_loaded(macula_crypto_nif),
is_nif_loaded().
%%%===================================================================
%%% Pure Erlang Fallback Implementation
%%%===================================================================
%% BLAKE3 constants
-define(BLAKE3_OUT_LEN, 32).
-define(BLAKE3_BLOCK_LEN, 64).
-define(BLAKE3_CHUNK_LEN, 1024).
%% BLAKE3 IV (same as BLAKE2s)
-define(IV, {
16#6A09E667, 16#BB67AE85, 16#3C6EF372, 16#A54FF53A,
16#510E527F, 16#9B05688C, 16#1F83D9AB, 16#5BE0CD19
}).
%% BLAKE3 message schedule permutation
-define(MSG_SCHEDULE, [
[0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15],
[2,6,3,10,7,0,4,13,1,11,12,5,9,14,15,8],
[3,4,10,12,13,2,7,14,6,5,9,0,11,15,8,1],
[10,7,12,9,14,3,13,15,4,0,11,2,5,8,1,6],
[12,13,9,11,15,10,14,8,7,2,5,3,0,1,6,4],
[9,14,11,5,8,12,15,1,13,3,0,10,2,6,4,7],
[11,15,5,0,1,9,8,6,14,10,2,12,3,4,7,13]
]).
%% @private Pure Erlang BLAKE3 implementation
erlang_blake3(Data) ->
%% For simplicity, use a simplified BLAKE3-like construction
%% that delegates to crypto for the core compression
%% This provides correct output but not optimal performance
blake3_hash(Data).
%% @private Streaming hash
erlang_blake3_streaming(Chunks) ->
Data = iolist_to_binary(Chunks),
erlang_blake3(Data).
%% @private Main BLAKE3 hash function
blake3_hash(Data) when byte_size(Data) =< ?BLAKE3_CHUNK_LEN ->
%% Small input - single chunk
compress_chunk(Data, 0, true, true);
blake3_hash(Data) ->
%% Large input - use tree hashing
ChunkHashes = chunk_data(Data, 0),
merge_hashes(ChunkHashes).
%% @private Split data into chunks and compress each
chunk_data(Data, ChunkIdx) ->
chunk_data(Data, ChunkIdx, []).
chunk_data(<<>>, _ChunkIdx, Acc) ->
lists:reverse(Acc);
chunk_data(Data, ChunkIdx, Acc) when byte_size(Data) =< ?BLAKE3_CHUNK_LEN ->
Hash = compress_chunk(Data, ChunkIdx, ChunkIdx =:= 0, true),
lists:reverse([Hash | Acc]);
chunk_data(<<Chunk:?BLAKE3_CHUNK_LEN/binary, Rest/binary>>, ChunkIdx, Acc) ->
Hash = compress_chunk(Chunk, ChunkIdx, ChunkIdx =:= 0, false),
chunk_data(Rest, ChunkIdx + 1, [Hash | Acc]).
%% @private Compress a single chunk
compress_chunk(Data, _ChunkIdx, _IsFirst, _IsLast) ->
%% Use SHA-256 as a stand-in for BLAKE3 compression
%% This is NOT cryptographically equivalent to BLAKE3 but provides
%% a functional fallback. The NIF provides real BLAKE3.
<<Hash:32/binary, _/binary>> = crypto:hash(sha256, Data),
Hash.
%% @private Merge chunk hashes into final hash using tree structure
merge_hashes([Hash]) ->
Hash;
merge_hashes(Hashes) ->
Pairs = pair_hashes(Hashes),
merge_hashes(Pairs).
%% @private Pair hashes and compress
pair_hashes([]) ->
[];
pair_hashes([H]) ->
[H];
pair_hashes([H1, H2 | Rest]) ->
Combined = crypto:hash(sha256, <<H1/binary, H2/binary>>),
[Combined | pair_hashes(Rest)].
%% @private Hex encode a binary
hex_encode(Bin) ->
<< <<(hex_char(N div 16)), (hex_char(N rem 16))>> || <<N>> <= Bin >>.
hex_char(N) when N < 10 -> N + $0;
hex_char(N) -> N - 10 + $a.
%%%===================================================================
%%% NIF Loading
%%%===================================================================
init() ->
%% NIF loading is handled by macula_crypto_nif via -on_load
%% This module just provides the Erlang stubs and fallback
ok.