libsodium_crypto_generichash_blake2b (libsodium v3.0.1)

View Source

BLAKE2b hashing, optionally keyed, salted, and personalized; the construction behind libsodium_crypto_generichash.

Output lengths must be between bytes_min/0 and bytes_max/0; keys may be empty or between keybytes_min/0 and keybytes_max/0 bytes. The salt_personal variants also take a saltbytes/0 byte salt and a personalbytes/0 byte personalization string, which separate otherwise identical uses of the same key.

The streaming functions thread an opaque state/0 through init/0,1,2 (or init_salt_personal/2,3,4), update/2, and final/1,2; each call returns a new state and leaves its argument unchanged. Updates over large inputs yield to other processes between chunks.

Digest = libsodium_crypto_generichash_blake2b:crypto_generichash_blake2b(<<"hello world">>),
32 = byte_size(Digest),
State0 = libsodium_crypto_generichash_blake2b:init(),
State1 = libsodium_crypto_generichash_blake2b:update(State0, <<"hello ">>),
State2 = libsodium_crypto_generichash_blake2b:update(State1, <<"world">>),
Digest = libsodium_crypto_generichash_blake2b:final(State2),
Salt = <<"0123456789abcdef">>,
Personal = <<"my-app-v1-hashes">>,
Salted = libsodium_crypto_generichash_blake2b:salt_personal(<<"hello world">>, Salt, Personal),
true = Salted =/= Digest.

Summary

Types

k()

A crypto_generichash_blake2b_KEYBYTES (32-byte) binary.

personal()

A crypto_generichash_blake2b_PERSONALBYTES (16-byte) binary.

salt()

A crypto_generichash_blake2b_SALTBYTES (16-byte) binary.

state()

An opaque native crypto_generichash_blake2b_state.

Functions

bytes()

Return crypto_generichash_blake2b_bytes(), in bytes.

bytes_max()

Return crypto_generichash_blake2b_bytes_max(), in bytes.

bytes_min()

Return crypto_generichash_blake2b_bytes_min(), in bytes.

crypto_generichash_blake2b(In)

Hash In with the optional Key, producing Outlen bytes.

crypto_generichash_blake2b(In, Key)

Hash In with the optional Key, producing Outlen bytes.

crypto_generichash_blake2b(Outlen, In, Key)

Hash In with the optional Key, producing Outlen bytes.

final(State)

Finish the streaming hash in State, producing Outlen bytes. The length should match the one passed to init/2 (default bytes/0).

final(State, Outlen)

Finish the streaming hash in State, producing Outlen bytes. The length should match the one passed to init/2 (default bytes/0).

init()

Start a streaming hash with the optional Key that will produce Outlen bytes. Defaults to bytes/0 bytes of output and no key.

init(Key)

Start a streaming hash with the optional Key that will produce Outlen bytes. Defaults to bytes/0 bytes of output and no key.

init(Key, Outlen)

Start a streaming hash with the optional Key that will produce Outlen bytes. Defaults to bytes/0 bytes of output and no key.

init_salt_personal(Salt, Personal)

Start a streaming hash with the optional Key, the saltbytes/0 byte Salt, and the personalbytes/0 byte Personal that will produce Outlen bytes. Defaults to bytes/0 bytes of output and no key.

init_salt_personal(Key, Salt, Personal)

Start a streaming hash with the optional Key, the saltbytes/0 byte Salt, and the personalbytes/0 byte Personal that will produce Outlen bytes. Defaults to bytes/0 bytes of output and no key.

init_salt_personal(Key, Outlen, Salt, Personal)

Start a streaming hash with the optional Key, the saltbytes/0 byte Salt, and the personalbytes/0 byte Personal that will produce Outlen bytes. Defaults to bytes/0 bytes of output and no key.

keybytes()

Return crypto_generichash_blake2b_keybytes(), in bytes.

keybytes_max()

Return crypto_generichash_blake2b_keybytes_max(), in bytes.

keybytes_min()

Return crypto_generichash_blake2b_keybytes_min(), in bytes.

keygen()

Generate a random keybytes/0 byte key.

personalbytes()

Return crypto_generichash_blake2b_personalbytes(), in bytes.

salt_personal(In, Salt, Personal)

Hash In with the optional Key, the saltbytes/0 byte Salt, and the personalbytes/0 byte Personal, producing Outlen bytes.

salt_personal(In, Key, Salt, Personal)

Hash In with the optional Key, the saltbytes/0 byte Salt, and the personalbytes/0 byte Personal, producing Outlen bytes.

salt_personal(Outlen, In, Key, Salt, Personal)

Hash In with the optional Key, the saltbytes/0 byte Salt, and the personalbytes/0 byte Personal, producing Outlen bytes.

saltbytes()

Return crypto_generichash_blake2b_saltbytes(), in bytes.

statebytes()

Return crypto_generichash_blake2b_statebytes(), in bytes.

update(State, In)

Absorb In into State and return the updated state.

Types

k()

-type k() :: <<_:256>>.

A crypto_generichash_blake2b_KEYBYTES (32-byte) binary.

personal()

-type personal() :: <<_:128>>.

A crypto_generichash_blake2b_PERSONALBYTES (16-byte) binary.

salt()

-type salt() :: <<_:128>>.

A crypto_generichash_blake2b_SALTBYTES (16-byte) binary.

state()

-type state() :: libsodium_nif:crypto_generichash_blake2b_state().

An opaque native crypto_generichash_blake2b_state.

Operations never modify a state: each returns a new one, so earlier states remain valid and can be reused or shared between processes. States cannot be serialized; they exist only within the running VM.

Functions

bytes()

-spec bytes() -> Result when Result :: 32.

Return crypto_generichash_blake2b_bytes(), in bytes.

bytes_max()

-spec bytes_max() -> Result when Result :: 64.

Return crypto_generichash_blake2b_bytes_max(), in bytes.

bytes_min()

-spec bytes_min() -> Result when Result :: 16.

Return crypto_generichash_blake2b_bytes_min(), in bytes.

crypto_generichash_blake2b(In)

-spec crypto_generichash_blake2b(In) -> Result when In :: binary(), Result :: binary() | -1.

Hash In with the optional Key, producing Outlen bytes.

Defaults to bytes/0 bytes of output and no key.

crypto_generichash_blake2b(In, Key)

-spec crypto_generichash_blake2b(In, Key) -> Result
                                    when In :: binary(), Key :: binary(), Result :: binary() | -1.

Hash In with the optional Key, producing Outlen bytes.

Defaults to bytes/0 bytes of output and no key.

crypto_generichash_blake2b(Outlen, In, Key)

-spec crypto_generichash_blake2b(Outlen, In, Key) -> Result
                                    when
                                        Outlen :: 16..64,
                                        In :: binary(),
                                        Key :: binary(),
                                        Result :: binary() | -1.

Hash In with the optional Key, producing Outlen bytes.

Defaults to bytes/0 bytes of output and no key.

final(State)

-spec final(State) -> Result when State :: state(), Result :: binary() | -1.

Finish the streaming hash in State, producing Outlen bytes. The length should match the one passed to init/2 (default bytes/0).

final(State, Outlen)

-spec final(State, Outlen) -> Result when State :: state(), Outlen :: 16..64, Result :: binary() | -1.

Finish the streaming hash in State, producing Outlen bytes. The length should match the one passed to init/2 (default bytes/0).

init()

-spec init() -> Result when Result :: state() | -1.

Start a streaming hash with the optional Key that will produce Outlen bytes. Defaults to bytes/0 bytes of output and no key.

init(Key)

-spec init(Key) -> Result when Key :: binary(), Result :: state() | -1.

Start a streaming hash with the optional Key that will produce Outlen bytes. Defaults to bytes/0 bytes of output and no key.

init(Key, Outlen)

-spec init(Key, Outlen) -> Result when Key :: binary(), Outlen :: 16..64, Result :: state() | -1.

Start a streaming hash with the optional Key that will produce Outlen bytes. Defaults to bytes/0 bytes of output and no key.

init_salt_personal(Salt, Personal)

-spec init_salt_personal(Salt, Personal) -> Result
                            when Salt :: salt(), Personal :: personal(), Result :: state() | -1.

Start a streaming hash with the optional Key, the saltbytes/0 byte Salt, and the personalbytes/0 byte Personal that will produce Outlen bytes. Defaults to bytes/0 bytes of output and no key.

init_salt_personal(Key, Salt, Personal)

-spec init_salt_personal(Key, Salt, Personal) -> Result
                            when
                                Key :: binary(),
                                Salt :: salt(),
                                Personal :: personal(),
                                Result :: state() | -1.

Start a streaming hash with the optional Key, the saltbytes/0 byte Salt, and the personalbytes/0 byte Personal that will produce Outlen bytes. Defaults to bytes/0 bytes of output and no key.

init_salt_personal(Key, Outlen, Salt, Personal)

-spec init_salt_personal(Key, Outlen, Salt, Personal) -> Result
                            when
                                Key :: binary(),
                                Outlen :: 16..64,
                                Salt :: salt(),
                                Personal :: personal(),
                                Result :: state() | -1.

Start a streaming hash with the optional Key, the saltbytes/0 byte Salt, and the personalbytes/0 byte Personal that will produce Outlen bytes. Defaults to bytes/0 bytes of output and no key.

keybytes()

-spec keybytes() -> Result when Result :: 32.

Return crypto_generichash_blake2b_keybytes(), in bytes.

keybytes_max()

-spec keybytes_max() -> Result when Result :: 64.

Return crypto_generichash_blake2b_keybytes_max(), in bytes.

keybytes_min()

-spec keybytes_min() -> Result when Result :: 16.

Return crypto_generichash_blake2b_keybytes_min(), in bytes.

keygen()

-spec keygen() -> Result when Result :: k().

Generate a random keybytes/0 byte key.

personalbytes()

-spec personalbytes() -> Result when Result :: 16.

Return crypto_generichash_blake2b_personalbytes(), in bytes.

salt_personal(In, Salt, Personal)

-spec salt_personal(In, Salt, Personal) -> Result
                       when
                           In :: binary(),
                           Salt :: salt(),
                           Personal :: personal(),
                           Result :: binary() | -1.

Hash In with the optional Key, the saltbytes/0 byte Salt, and the personalbytes/0 byte Personal, producing Outlen bytes.

Defaults to bytes/0 bytes of output and no key.

salt_personal(In, Key, Salt, Personal)

-spec salt_personal(In, Key, Salt, Personal) -> Result
                       when
                           In :: binary(),
                           Key :: binary(),
                           Salt :: salt(),
                           Personal :: personal(),
                           Result :: binary() | -1.

Hash In with the optional Key, the saltbytes/0 byte Salt, and the personalbytes/0 byte Personal, producing Outlen bytes.

Defaults to bytes/0 bytes of output and no key.

salt_personal(Outlen, In, Key, Salt, Personal)

-spec salt_personal(Outlen, In, Key, Salt, Personal) -> Result
                       when
                           Outlen :: 16..64,
                           In :: binary(),
                           Key :: binary(),
                           Salt :: salt(),
                           Personal :: personal(),
                           Result :: binary() | -1.

Hash In with the optional Key, the saltbytes/0 byte Salt, and the personalbytes/0 byte Personal, producing Outlen bytes.

Defaults to bytes/0 bytes of output and no key.

saltbytes()

-spec saltbytes() -> Result when Result :: 16.

Return crypto_generichash_blake2b_saltbytes(), in bytes.

statebytes()

-spec statebytes() -> Result when Result :: 384.

Return crypto_generichash_blake2b_statebytes(), in bytes.

update(State, In)

-spec update(State, In) -> Result when State :: state(), In :: binary(), Result :: state() | -1.

Absorb In into State and return the updated state.