/ 
Crypt-Sodium-XS-0.000039
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 $tag = $ota->onetimeauth($msg, $key);
die "message tampered!" unless $ota->verify($tag, $msg, $key);

DESCRIPTION

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

ATTRIBUTES

primitive

my $primitive = $ota->primitive;
$ota->primitive('poly1305');

Gets or sets the primitive used for all operations by this object. Note this can be default.

METHODS

primitives

my @primitives = Crypt::Sodium::XS::OO::onetimeauth->primitives;
my @primitives = $ota->primitives;

Returns a list of all supported primitive names, including default.

Can be called as a class method.

PRIMITIVE

my $primitive = $ota->PRIMITIVE;

Returns the primitive used for all operations by this object. Note this will never be default but would instead be the primitive it represents.

init

my $multipart = $ota->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".

keygen

my $key = $ota->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 "KEYBYTES" bytes.

verify

my $is_valid = $ota->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.

onetimeauth

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

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

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

Returns an authentication tag of "BYTES" bytes.

BYTES

my $tag_size = $ota->BYTES;

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

KEYBYTES

my $key_size = $ota->KEYBYTES;

Returns the size, in bytes, of a secret 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 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

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.