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 $mac = onetimeauth($msg, $key);
die "message tampered!" unless onetimeauth_verify($mac, $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 as documented below. A separate import tag is provided for each of the primitives listed in "PRIMITIVES". For example, :poly1305 imports onetimeauth_poly1305_verify. You should use at least one import tag.

onetimeauth

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

onetimeauth_init

my $multipart = onetimeauth_init();

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

onetimeauth_keygen

my $key = onetimeauth_keygen();

onetimeauth_verify

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

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 mac 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;

final

my $mac = $multipart->final;

update

$multipart->update($message);
$multipart->update(@messages);

CONSTANTS

onetimeauth_PRIMITIVE

my $default_primitive = onetimeauth_PRIMITIVE();

onetimeauth_BYTES

my $mac_length = onetimeauth_BYTES();

onetimeauth_KEYBYTES

my $key_length = onetimeauth_KEYBYTES();

PRIMITIVES

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

• poly1305

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:

• IRC channel #sodium on irc.perl.org.

• Email the author directly.

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.

cpanm Crypt::Sodium::XS

perl -MCPAN -e shell
install Crypt::Sodium::XS