libsodium_crypto_onetimeauth_poly1305 (libsodium v3.0.1)
View SourceOne-time message authentication with Poly1305.
A keybytes/0 byte key must be used to authenticate a single message
only; reusing it lets an attacker forge tags. Derive a fresh key per
message (for example from a stream cipher), or use
libsodium_crypto_auth for a reusable key.
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.
Key = libsodium_crypto_onetimeauth_poly1305:keygen(),
Tag = libsodium_crypto_onetimeauth_poly1305:crypto_onetimeauth_poly1305(<<"message">>, Key),
0 = libsodium_crypto_onetimeauth_poly1305:verify(Tag, <<"message">>, Key),
-1 = libsodium_crypto_onetimeauth_poly1305:verify(Tag, <<"forged">>, Key),
State0 = libsodium_crypto_onetimeauth_poly1305:init(Key),
State1 = libsodium_crypto_onetimeauth_poly1305:update(State0, <<"mess">>),
State2 = libsodium_crypto_onetimeauth_poly1305:update(State1, <<"age">>),
Tag = libsodium_crypto_onetimeauth_poly1305:final(State2).Summary
Types
A crypto_onetimeauth_poly1305_BYTES (16-byte) binary.
A crypto_onetimeauth_poly1305_KEYBYTES (32-byte) binary.
A crypto_onetimeauth_poly1305_KEYBYTES (32-byte) binary.
A crypto_onetimeauth_poly1305_BYTES (16-byte) binary.
An opaque native crypto_onetimeauth_poly1305_state.
Functions
Return crypto_onetimeauth_poly1305_bytes(), in bytes.
Compute the bytes/0 byte tag of In under the one-time keybytes/0 byte key K.
Finish the streaming authenticator in State, returning a bytes/0 byte tag.
Start a streaming authenticator with the one-time keybytes/0 byte Key.
Return crypto_onetimeauth_poly1305_keybytes(), in bytes.
Generate a random keybytes/0 byte key.
Return crypto_onetimeauth_poly1305_statebytes(), in bytes.
Absorb In into State and return the updated state.
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
-type h() :: <<_:128>>.
A crypto_onetimeauth_poly1305_BYTES (16-byte) binary.
-type k() :: <<_:256>>.
A crypto_onetimeauth_poly1305_KEYBYTES (32-byte) binary.
-type key() :: <<_:256>>.
A crypto_onetimeauth_poly1305_KEYBYTES (32-byte) binary.
-type out() :: <<_:128>>.
A crypto_onetimeauth_poly1305_BYTES (16-byte) binary.
-type state() :: libsodium_nif:crypto_onetimeauth_poly1305_state().
An opaque native crypto_onetimeauth_poly1305_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
-spec bytes() -> Result when Result :: 16.
Return crypto_onetimeauth_poly1305_bytes(), in bytes.
-spec crypto_onetimeauth_poly1305(In, K) -> Result when In :: binary(), K :: k(), Result :: out() | -1.
Compute the bytes/0 byte tag of In under the one-time keybytes/0 byte key K.
Finish the streaming authenticator in State, returning a bytes/0 byte tag.
Start a streaming authenticator with the one-time keybytes/0 byte Key.
-spec keybytes() -> Result when Result :: 32.
Return crypto_onetimeauth_poly1305_keybytes(), in bytes.
-spec keygen() -> Result when Result :: k().
Generate a random keybytes/0 byte key.
-spec statebytes() -> Result when Result :: 256.
Return crypto_onetimeauth_poly1305_statebytes(), in bytes.
Absorb In into State and return the updated state.
Check in constant time that H is the tag of In under the key K.
Returns 0 when it is valid and -1 otherwise.