/ 
Crypt-Sodium-XS-0.000039
River stage zero No dependents
/ Crypt::Sodium::XS::onetimeauth

NAME

Crypt::Sodium::XS::onetimeauth - Single-use secret key message authentication

SYNOPSIS

use Crypt::Sodium::XS::onetimeauth ":default";

# NOTE: use a new key for every message
my $key = onetimeauth_keygen();
my $msg = "authenticate me";

my $tag = onetimeauth($msg, $key);
die "message tampered!" unless onetimeauth_verify($tag, $msg, $key);

DESCRIPTION

Crypt::Sodium::XS::onetimeauth uses Poly1305, a Wegman-Carter authenticator designed by D. J. Bernstein. Poly1305 takes a 32-byte, one-time key and a message and produces a 16-byte tag that authenticates the message such that an attacker has a negligible chance of producing a valid tag for a inauthentic message.

Poly1305 keys have to be:

  • secret

    An attacker can compute a valid authentication tag for any message, for any given key. The security of Poly1305 relies on the fact that attackers don't know the key being used to compute the tag. This implies that they have to be:

  • unpredictable

    Do not use timestamps or counters.

  • unique

    Never reuse a key. A new key is required for every single message. The key can be recovered if two messages are authenticated with the same key.

The standard way to use Poly1305's is to derive a dedicated subkey from a (key, nonce) tuple, for example by taking the first bytes generated by a stream cipher.

Due to its output size, Poly1305 is recommended for online protocols, exchanging many small messages, rather than for authenticating very large files.

Finally, Poly1305 is not a replacement for a hash function.

FUNCTIONS

Nothing is exported by default. A :default tag imports the functions and constants documented below. A separate :<primitive> import tag is provided for each of the primitives listed in "PRIMITIVES". These tags import the onetimeauth_<primitive>_* functions and constants for that primitive. A :all tag imports everything.

onetimeauth

onetimeauth_<primitive>

my $tag = onetimeauth($message, $key);

$message is the message to authenticate. It may be a Crypt::Sodium::XS::MemVault.

$key is a secret key. It must be "onetimeauth_KEYBYTES" bytes. It may be a Crypt::Sodium::XS::MemVault.

Returns an authentication tag of "onetimeauth_BYTES" bytes.

onetimeauth_init

onetimeauth_<primitive>_init

my $multipart = onetimeauth_init($flags);

$flags is optional. It is the flags used for the multipart protected memory object. See Crypt::Sodium::XS::ProtMem.

Returns a multipart onetimeauth object. See "MULTI-PART INTERFACE".

onetimeauth_keygen

onetimeauth_<primitive>_keygen

my $key = onetimeauth_keygen($flags);

$flags is optional. It is the flags used for the $key Crypt::Sodium::XS::MemVault. See Crypt::Sodium::XS::ProtMem.

Returns a Crypt::Sodium::XS::MemVault: a secret key of "onetimeauth_KEYBYTES" bytes.

onetimeauth_verify

onetimeauth_<primitive>_verify

my $is_valid = onetimeauth_verify($tag, $message, $key);

$tag is the authentication tag to verify. It must be "BYTES" bytes.

$message is the message to authenticate.

$key is the secret key to use for authentication of the tag. It must be "KEYBYTES" bytes. It may be a Crypt::Sodium::XS::MemVault.

Returns true if the authentication tag $tag validly authenticates $message with $key, false otherwise.

MULTI-PART INTERFACE

A multipart onetimeauth object is created by calling the "onetimeauth_init" function. Data to be authenticated is added by calling the "update" method of that object as many times as desired. An output tag is generated by calling its "final" method. Do not use the object after calling "final".

The multipart onetimeauth object is an opaque object which provides the following methods:

clone

my $multipart_copy = $multipart->clone;

Returns a cloned copy of the multipart onetimeauth object, duplicating its internal state.

final

my $tag = $multipart->final;

Returns an authentication tag of "BYTES" bytes.

Once final has been called, the hashing object must not be used further.

update

$multipart->update(@messages);

Adds all given arguments (stringified) to authenticated data. Any argument may be a Crypt::Sodium::XS::MemVault.

CONSTANTS

onetimeauth_PRIMITIVE

my $default_primitive = onetimeauth_PRIMITIVE();

Returns the name of the default primitive.

onetimeauth_BYTES

onetimeauth_<primitive>_BYTES

my $tag_size = onetimeauth_BYTES();

Returns the size, in bytes, of an authentication tag.

onetimeauth_KEYBYTES

onetimeauth_<primitive>_KEYBYTES

my $key_size = onetimeauth_KEYBYTES();

Returns the size, in bytes, of a secret key.

PRIMITIVES

All constants (except _PRIMITIVE) and functions have onetimeauth_<primitive>-prefixed couterparts (e.g., onetimeauth_poly1305_keypair, onetimeauth_poly1305_KEYBYTES).

  • poly1305 (default)

SEE ALSO

Crypt::Sodium::XS
Crypt::Sodium::XS::OO::onetimeauth
https://doc.libsodium.org/advanced/poly1305

FEEDBACK

For reporting bugs, giving feedback, submitting patches, etc. please use the following:

AUTHOR

Brad Barden <perlmodules@5c30.org>

COPYRIGHT & LICENSE

Copyright (c) 2022 Brad Barden. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.