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

NAME

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

SYNOPSIS

use Crypt::Sodium::XS;
my $ota = Crypt::Sodium::XS->onetimeauth;

# NOTE: use a new key for every message
my $key = $ota->keygen;
my $msg = "authenticate me";

my $mac = $ota->onetimeauth($msg, $key);
die "message tampered!" unless $ota->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.

CONSTRUCTOR

new

my $ota = Crypt::Sodium::XS::OO::onetimeauth->new;
my $ota = Crypt::Sodium::XS::OO::onetimeauth->new(primitive => 'poly1305');
my $ota = Crypt::Sodium::XS->onetimeauth;

Returns a new onetimeauth object for the given primitive. If not given, the default primitive is default.

METHODS

PRIMITIVE

my $ota = Crypt::Sodium::XS::OO::onetimeauth->new;
my $default_primitive = $ota->PRIMITIVE;

BYTES

my $mac_length = $ota->BYTES;

KEYBYTES

my $key_length = $ota->KEYBYTES;

primitives

my @primitives = $pwhash->primitives;

Returns a list of all supported primitive names (including 'default').

init

my $multipart = $ota->init;

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

onetimeauth

my $mac = $ota->onetimeauth($message, $key);

keygen

my $key = $ota->keygen;

verify

my $is_valid = $ota->verify($mac, $message, $key);

MULTI-PART INTERFACE

A multipart onetimeauth object is created by calling the "init" method. 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

SEE ALSO

Crypt::Sodium::XS
Crypt::Sodium::XS::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.