libsodium_crypto_auth_hmacsha512 (libsodium v3.0.1)

View Source

Secret-key message authentication with HMAC-SHA-512.

The one-shot functions take a keybytes/0 byte key and produce bytes/0 byte tags. The streaming functions thread an opaque state/0 through init/1, update/2, and final/1; each call returns a new state and leaves its argument unchanged. Updates over large inputs yield to other processes between chunks. Unlike the one-shot functions, init/1 accepts a key of any length, as HMAC does.

verify/3 compares tags in constant time.

Key = libsodium_crypto_auth_hmacsha512:keygen(),
Tag = libsodium_crypto_auth_hmacsha512:crypto_auth_hmacsha512(<<"message">>, Key),
0 = libsodium_crypto_auth_hmacsha512:verify(Tag, <<"message">>, Key),
-1 = libsodium_crypto_auth_hmacsha512:verify(Tag, <<"forged">>, Key),
State0 = libsodium_crypto_auth_hmacsha512:init(Key),
State1 = libsodium_crypto_auth_hmacsha512:update(State0, <<"mess">>),
State2 = libsodium_crypto_auth_hmacsha512:update(State1, <<"age">>),
Tag = libsodium_crypto_auth_hmacsha512:final(State2).

Summary

Types

h()

A crypto_auth_hmacsha512_BYTES (64-byte) binary.

k()

A crypto_auth_hmacsha512_KEYBYTES (32-byte) binary.

out()

A crypto_auth_hmacsha512_BYTES (64-byte) binary.

state()

An opaque native crypto_auth_hmacsha512_state.

Functions

bytes()

Return crypto_auth_hmacsha512_bytes(), in bytes.

crypto_auth_hmacsha512(In, K)

Compute the bytes/0 byte authentication tag of In under the keybytes/0 byte key K.

final(State)

Finish the streaming authenticator in State, returning a bytes/0 byte tag.

init(Key)

Start a streaming authenticator keyed with Key, which may be of any length, and return its state.

keybytes()

Return crypto_auth_hmacsha512_keybytes(), in bytes.

keygen()

Generate a random keybytes/0 byte key.

statebytes()

Return crypto_auth_hmacsha512_statebytes(), in bytes.

update(State, In)

Absorb In into State and return the updated state.

verify(H, In, K)

Check in constant time that H is the tag of In under the key K. Returns 0 when it is valid and -1 otherwise.

Types

h()

-type h() :: <<_:512>>.

A crypto_auth_hmacsha512_BYTES (64-byte) binary.

k()

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

A crypto_auth_hmacsha512_KEYBYTES (32-byte) binary.

out()

-type out() :: <<_:512>>.

A crypto_auth_hmacsha512_BYTES (64-byte) binary.

state()

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

An opaque native crypto_auth_hmacsha512_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 :: 64.

Return crypto_auth_hmacsha512_bytes(), in bytes.

crypto_auth_hmacsha512(In, K)

-spec crypto_auth_hmacsha512(In, K) -> Result when In :: binary(), K :: k(), Result :: out() | -1.

Compute the bytes/0 byte authentication tag of In under the keybytes/0 byte key K.

final(State)

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

Finish the streaming authenticator in State, returning a bytes/0 byte tag.

init(Key)

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

Start a streaming authenticator keyed with Key, which may be of any length, and return its state.

keybytes()

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

Return crypto_auth_hmacsha512_keybytes(), in bytes.

keygen()

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

Generate a random keybytes/0 byte key.

statebytes()

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

Return crypto_auth_hmacsha512_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.

verify(H, In, K)

-spec verify(H, In, K) -> Result when H :: h(), In :: binary(), K :: k(), Result :: 0 | -1.

Check in constant time that H is the tag of In under the key K. Returns 0 when it is valid and -1 otherwise.